MCP Calendar Invoice Server

A TypeScript-based Model Context Protocol (MCP) server that integrates with calendar systems to calculate working days and generate professional PDF invoices for freelancers and consultants.

• Smart Business Logic: Automatically excludes weekends, holidays, and calendar events
• Multi-Country Support: Holiday detection for 100+ countries via Nager.Date API
• Google Calendar Integration: Excludes personal events from working days calculations
• Detailed Breakdown: Day-by-day analysis with reasons for exclusions

• Automated PDF Creation: Generate beautiful invoices using Puppeteer
• Working Days Integration: Automatically calculates billable days and totals
• Professional Templates: Modern, responsive HTML templates with print optimization
• Multi-Currency Support: EUR, USD, and other currencies with proper formatting
• Tax Calculations: Configurable tax rates with automatic calculations

• 3 Powerful Tools: get_working_days, get_holidays, generate_invoice
• Resource Access: Direct access to generated PDFs and templates via MCP resources
• Claude Desktop Ready: Seamless integration with Claude Desktop
• Tool + Resource Pattern: Proper MCP architecture implementation

• Node.js 18+
• npm or yarn
• Claude Desktop (for MCP integration)

# Clone the repository
git clone https://github.com/Sitraka003/mcp-calendar-invoice-server.git
cd mcp-calendar-invoice-server

# Install dependencies
npm install

# Build the project
npm run build

Create a .env file (optional - defaults provided):

# Google Calendar API (optional)
GOOGLE_CREDENTIALS_PATH=./credentials/google-service-account.json
GOOGLE_CALENDAR_ID=primary

# Company Information
COMPANY_NAME=FreelancePro Services
COMPANY_EMAIL=contact@freelancepro.com
COMPANY_PHONE=+33 1 23 45 67 89

# Invoice Configuration
DEFAULT_CURRENCY=EUR
DEFAULT_DAILY_RATE=500
OUTPUT_DIRECTORY=./output/invoices

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "calendar-invoice-server": {
      "command": "tsx",
      "args": ["/path/to/your/project/src/index.ts"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Calculate working days in a date range with comprehensive exclusions.

Parameters:

• startDate (string): Start date in YYYY-MM-DD format
• endDate (string): End date in YYYY-MM-DD format
• countryCode (string, optional): Country for holidays (default: "FR")
• includeCalendarEvents (boolean, optional): Exclude calendar events (default: true)
• calendarId (string, optional): Google Calendar ID

Example:

Calculate working days from 2024-01-01 to 2024-01-31 for France

Retrieve holidays for specific countries and years with filtering options.

Parameters:

• year (number): Year (2000-2050)
• countryCode (string, optional): Country code (default: "FR")
• startDate (string, optional): Filter start date
• endDate (string, optional): Filter end date

Example:

Get French holidays for 2024 between March and June

Generate professional PDF invoices with automatic working days calculation.

Parameters:

• clientName (string): Client or company name
• startDate (string): Work period start date
• endDate (string): Work period end date
• dailyRate (number): Daily rate in euros
• clientAddress (string, optional): Client address
• clientEmail (string, optional): Client email
• description (string, optional): Work description
• taxRate (number, optional): Tax rate as decimal (0.20 = 20%)
• currency (string, optional): Currency code (default: "EUR")

Example:

Generate an invoice for "Acme Corporation" from 2024-01-01 to 2024-01-31 at €500/day

Access the HTML template used for invoice generation.

Access generated invoice PDF files by invoice ID (e.g., file://invoices/INV-2025-06-123456.pdf).

JSON listing of recently generated invoices with metadata.

The server implements the proper MCP architecture:

1. Tools perform actions (calculate working days, generate PDFs)
2. Resources provide access to content (PDF files, templates)
3. Workflow: Tool creates content → Returns metadata with resourceUri → Resource accessible for content

src/
├── index.ts              # MCP server entry point
├── services/
│   ├── calendar.ts       # Google Calendar integration
│   ├── holidays.ts       # Holiday API with provider pattern
│   └── invoice.ts        # PDF invoice generation
├── utils/
│   ├── working-days.ts   # Business days calculation
│   └── date-helpers.ts   # Date utility functions
├── types/
│   ├── calendar.ts       # Calendar type definitions
│   ├── holidays.ts       # Holiday type definitions
│   └── invoice.ts        # Invoice type definitions
└── config/
    └── environment.ts    # Configuration management

User: "How many working days are there in January 2024 in France?"
→ Tool: get_working_days
→ Result: 23 working days (excludes weekends + New Year's Day)

User: "Generate an invoice for Acme Corp for January 2024"
→ Tool: generate_invoice (creates PDF)
→ Resource: file://invoices/INV-2025-06-123456.pdf (access PDF)
→ Result: Invoice metadata + direct PDF access

User: "Show me all French holidays in Q2 2024"
→ Tool: get_holidays (with date filtering)
→ Result: Easter Monday, Labour Day, Victory Day, Ascension Day, etc.

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

npm run dev          # Development server with hot reload
npm run build        # Build TypeScript to JavaScript
npm run start        # Start production server
npm run test         # Run test suite
npm run clean        # Clean build artifacts

calendar-mcp-server/
├── src/                 # Source code
├── templates/           # Invoice HTML templates
├── output/invoices/     # Generated PDF invoices
├── credentials/         # Google API credentials (optional)
├── docs/               # Documentation
└── tests/              # Test files

The server supports holiday detection for 100+ countries including:

• 🇫🇷 France (FR) - Default
• 🇺🇸 United States (US)
• 🇬🇧 United Kingdom (GB)
• 🇩🇪 Germany (DE)
• 🇨🇦 Canada (CA)
• 🇦🇺 Australia (AU)
• 🇪🇸 Spain (ES)
• 🇮🇹 Italy (IT)
• And many more...

• Node.js 18.0.0 or higher
• Memory: 2GB+ RAM (for PDF generation)
• Storage: File system write access for invoice output
• Network: Internet access for holiday API calls

• Google Calendar API: For calendar event exclusions
• Claude Desktop: For MCP client integration

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

This project is licensed under the MIT License - see the LICENSE file for details.

• FastMCP - TypeScript MCP framework
• Nager.Date - Holiday API service
• Google Calendar API - Calendar integration
• Puppeteer - PDF generation
• Claude Desktop - MCP client platform

• Issues: GitHub Issues
• Documentation: Project Wiki
• MCP Protocol: Model Context Protocol

Built with ❤️ for the freelancer community using the Model Context Protocol