FreshBooks MCP Server

# FreshBooks MCP Server A Model Context Protocol (MCP) server providing complete FreshBooks integration for Claude and other MCP-compatible AI assistants. [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](#testing) ## Features - **Complete SDK Parity** - 87 tools covering all major FreshBooks functionality - **22 Entity Categories** - Full coverage of accounting, invoicing, time tracking, and more - **Time Tracking** - Log time, manage timers, track billable hours - **Invoicing & Billing** - Create invoices, manage bills, handle payments - **Expense Management** - Track expenses, categorize spending, manage vendors - **Client & Project Management** - Full CRM and project capabilities - **Financial Reports** - Profit/loss, tax summaries, and more - **OAuth2 Authentication** - Secure token-based authentication with auto-refresh ## Installation ```bash npm install freshbooks-mcp ``` ## Quick Start ### 1. Get FreshBooks Credentials 1. Go to [FreshBooks Developer Portal](https://my.freshbooks.com/#/developer) 2. Create a new application 3. Set redirect URI to: `https://freshbooks.goodsamsoftware.com/callback` 4. Note your Client ID and Client Secret ### 2. Configure Claude Desktop Add to your Claude Desktop configuration (`claude_desktop_config.json`): ```json { "mcpServers": { "freshbooks": { "command": "npx", "args": ["freshbooks-mcp"], "env": { "FRESHBOOKS_CLIENT_ID": "your-client-id", "FRESHBOOKS_CLIENT_SECRET": "your-client-secret", "FRESHBOOKS_REDIRECT_URI": "https://freshbooks.goodsamsoftware.com/callback" } } } } ``` ### 3. Authenticate Ask Claude: > "Connect me to FreshBooks" Claude will guide you through OAuth authentication. After authorizing in FreshBooks, you'll see the authorization code on our [hosted callback page](https://freshbooks.goodsamsoftware.com) - just copy it and paste it back to Claude. ### 4. Start Using Example prompts: - "Log 2 hours on the Website Redesign project" - "Show me my time entries for this week" - "Start a timer for client meeting" - "Create an invoice for Acme Corp for $1,500" - "What's my profit/loss this month?" ## Available Tools (87 total) ### Authentication (5 tools) | Tool | Description | |------|-------------| | `auth_status` | Check authentication status | | `auth_get_url` | Get OAuth authorization URL | | `auth_exchange_code` | Exchange auth code for tokens | | `auth_refresh` | Refresh access token | | `auth_revoke` | Revoke authentication | ### Time Tracking (5 tools) | Tool | Description | |------|-------------| | `timeentry_list` | List time entries with filters | | `timeentry_single` | Get time entry by ID | | `timeentry_create` | Create time entry | | `timeentry_update` | Update time entry | | `timeentry_delete` | Delete time entry | ### Timer Management (4 tools) | Tool | Description | |------|-------------| | `timer_start` | Start a timer | | `timer_stop` | Stop timer and log time | | `timer_current` | Get running timer(s) | | `timer_discard` | Delete timer without logging | ### Invoicing (5 tools) | Tool | Description | |------|-------------| | `invoice_list` | List invoices | | `invoice_single` | Get invoice by ID | | `invoice_create` | Create invoice | | `invoice_update` | Update invoice | | `invoice_delete` | Delete invoice | ### Clients (5 tools) | Tool | Description | |------|-------------| | `client_list` | List clients | | `client_single` | Get client by ID | | `client_create` | Create client | | `client_update` | Update client | | `client_delete` | Delete client | ### Projects (5 tools) | Tool | Description | |------|-------------| | `project_list` | List projects | | `project_single` | Get project by ID | | `project_create` | Create project | | `project_update` | Update project | | `project_delete` | Delete project | ### Expenses (5 tools) | Tool | Description | |------|-------------| | `expense_list` | List expenses | | `expense_single` | Get expense by ID | | `expense_create` | Create expense | | `expense_update` | Update expense | | `expense_delete` | Delete expense | ### Bills & Payments (15 tools) | Tool | Description | |------|-------------| | `bill_list` | List bills | | `bill_single` | Get bill by ID | | `bill_create` | Create bill | | `bill_update` | Update bill | | `bill_delete` | Delete bill | | `billpayment_list` | List bill payments | | `billpayment_single` | Get bill payment | | `billpayment_create` | Create bill payment | | `billpayment_update` | Update bill payment | | `billpayment_delete` | Delete bill payment | | `billvendor_list` | List vendors | | `billvendor_single` | Get vendor by ID | | `billvendor_create` | Create vendor | | `billvendor_update` | Update vendor | | `billvendor_delete` | Delete vendor | ### Additional Tools | Category | Tools | Description | |----------|-------|-------------| | **Credit Notes** | 5 | Create, manage credit notes | | **Expense Categories** | 3 | Manage expense categories | | **Items** | 5 | Product/service catalog | | **Journal Entries** | 5 | Manual accounting entries | | **Journal Entry Accounts** | 3 | Chart of accounts | | **Other Income** | 5 | Non-invoice income tracking | | **Payments** | 5 | Invoice payment tracking | | **Payment Options** | 2 | Payment gateway settings | | **Reports** | 3 | Financial reports | | **Services** | 5 | Billable service types | | **Tasks** | 5 | Project task management | | **User** | 1 | Current user info | | **Callbacks** | 5 | Webhook management | *See complete tool documentation in [docs/api/](docs/api/)* ## Configuration ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `FRESHBOOKS_CLIENT_ID` | Yes | OAuth client ID | | `FRESHBOOKS_CLIENT_SECRET` | Yes | OAuth client secret | | `FRESHBOOKS_REDIRECT_URI` | Yes | OAuth redirect URI | | `FRESHBOOKS_TOKEN_PATH` | No | Path for token storage | | `LOG_LEVEL` | No | Logging level (debug, info, warn, error) | ### Getting FreshBooks Credentials 1. Go to [FreshBooks Developer Portal](https://my.freshbooks.com/#/developer) 2. Create a new application 3. Note your Client ID and Client Secret 4. Set redirect URI to: `https://freshbooks.goodsamsoftware.com/callback` ### Advanced: Local HTTPS Setup If you prefer to use a local callback instead of our hosted callback page, you can set up local HTTPS certificates with [mkcert](https://github.com/FiloSottile/mkcert): **Windows (winget):** ```bash winget install FiloSottile.mkcert mkcert -install mkdir certs mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1 ``` **macOS (Homebrew):** ```bash brew install mkcert mkcert -install mkdir certs mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1 ``` **Linux:** ```bash # Install mkcert (see https://github.com/FiloSottile/mkcert#installation) mkcert -install mkdir certs mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1 ``` Then set your redirect URI to `https://localhost:3000/callback` in FreshBooks. The certificates will be valid for 3 years and trusted by your system. ## Development ```bash # Install dependencies npm install # Run in development mode npm run dev # Run tests npm test # Run tests with coverage npm run test:coverage # Type check npm run typecheck # Build for production npm run build ``` ## Testing The project has comprehensive test coverage: - **1,571 tests** across 93 test files - **100% code coverage** requirement - Mock factories for all FreshBooks entities - Error scenario coverage ```bash npm test # Run all tests npm run test:coverage # Run with coverage report ``` ## Architecture ``` src/ ├── server.ts # MCP server entry point ├── auth/ # OAuth2 authentication ├── client/ # FreshBooks SDK wrapper ├── errors/ # Error normalization ├── tools/ # MCP tool implementations (22 categories) │ ├── auth/ # Authentication tools │ ├── time-entry/ # Time tracking │ ├── timer/ # Timer management │ ├── invoice/ # Invoicing │ ├── client/ # Client management │ ├── project/ # Projects │ ├── expense/ # Expenses │ ├── bill/ # Bills │ └── ... # 14 more categories └── config/ # Configuration ``` ## Documentation - [API Reference](docs/api/) - Complete tool documentation - [Authentication Setup](docs/AUTH_SETUP.md) - OAuth configuration - [Claude Guide](docs/claude/) - Claude-optimized usage examples - [Examples](docs/examples/) - Workflow examples ## Error Handling All errors are normalized to MCP format with helpful context: ```json { "code": -32005, "message": "User-friendly message", "data": { "freshbooksError": { "code": "...", "message": "..." }, "recoverable": true, "suggestion": "What to do next" } } ``` ## License MIT License - see [LICENSE](LICENSE) for details. ## Credits - [FreshBooks Node.js SDK](https://github.com/freshbooks/freshbooks-nodejs-sdk) - [Model Context Protocol](https://modelcontextprotocol.io) - [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)