FreshBooks MCP Server
This server connects to FreshBooks accounting, providing 92 tools for comprehensive financial and project management via AI clients. Key capabilities include:
Authentication Management: Check status, get OAuth authorization URL, exchange authorization codes, and revoke tokens.
Invoices (6 tools): List, retrieve, create, update, delete, and generate shareable payment links.
Clients (5 tools): List, retrieve, create, update, and delete client records.
Time Tracking (9 tools): List, retrieve, create, update, and delete time entries; manage a running timer (start, stop, discard).
Projects (5 tools): List, retrieve, create, update, and delete projects.
Expenses (5 tools): List, retrieve, create, update, and delete expenses.
Payments (5 tools): List, retrieve, record, update, and delete invoice payments.
Bills (10 tools): List, retrieve, create, update, delete, and archive bills; manage bill payments (list, retrieve, record, update, delete).
Vendors (5 tools): List, retrieve, create, update, and delete vendors.
Reports (3 read-only tools): Profit & loss, payments collected, and tax summary.
Additional Functionality: Credit notes, expense categories, items, journal entries, other income, payment options, services, tasks, user information, and webhooks (callbacks).
41 tools are read-only; write operations include a confirmation step. The server can be used hosted or self-hosted and supports multiple MCP clients (Claude, ChatGPT, Cursor, etc.).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@FreshBooks MCP Server create an invoice for Acme Corp for $1,500"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
FreshBooks MCP by Good Samaritan Software
Manage your FreshBooks in plain English from Claude or ChatGPT. FreshBooks MCP is a fully hosted service — no local install, no API keys to manage, one OAuth sign-in to your FreshBooks account. 41 of the 92 tools are read-only by default; write operations surface a confirmation step in your AI client before any data changes.
Get started → · Documentation · Pricing — from $29/mo
Currently available in the United States. International waitlist available at the link above.
What you can do
92 tools spanning invoices, clients, expenses, time tracking, projects, payments, vendors, bills, and reports — with 41 read-only tools for safe lookups and 51 write tools for full account management.
Example prompts:
"Show me all unpaid invoices over $500"
"Create an invoice for Acme Corp for $1,500 due in 30 days"
"What's my profit and loss for this year?"
"Log 2 hours on the Website Redesign project"
"Start a timer for this client meeting"
"Record a $45 office supplies expense"
"List all vendors I've paid this quarter"
Related MCP server: mcp-freshbooks
Quick Start — Hosted Service (Recommended)
The fastest path: subscribe, connect FreshBooks, paste your config into your AI client.
Claude (Desktop, Code, Web)
Go to freshbooks.goodsamsoftware.com, create an account, and connect your FreshBooks account. Copy your API key from the dashboard.
Add to your Claude Desktop config (
claude_desktop_config.json) or Claude Code project config (.mcp.json):
{
"mcpServers": {
"freshbooks": {
"command": "npx",
"args": ["mcp-remote", "https://freshbooks.goodsamsoftware.com/api/mcp", "--header", "Authorization:Bearer YOUR_API_KEY"]
}
}
}ChatGPT
In ChatGPT, go to Settings → Connectors → Add connector.
Enter the MCP server URL:
https://freshbooks.goodsamsoftware.com/api/mcpComplete the OAuth flow to connect your FreshBooks account.
Other MCP Clients (Cursor, Windsurf, Continue, Cline, etc.)
Use the same mcp-remote configuration shown above, substituting your client's config location.
Available Tools (92 total)
Invoices (6 tools)
Tool | Read-only | Description |
| ✓ | List invoices with filters |
| ✓ | Get invoice by ID |
| ✓ | Get shareable payment link |
| Create invoice | |
| Update invoice | |
| Delete invoice |
Clients (5 tools)
Tool | Read-only | Description |
| ✓ | List clients |
| ✓ | Get client by ID |
| Create client | |
| Update client | |
| Delete client |
Time Tracking (9 tools)
Tool | Read-only | Description |
| ✓ | List time entries with filters |
| ✓ | Get time entry by ID |
| ✓ | Get running timer |
| Create time entry | |
| Update time entry | |
| Delete time entry | |
| Start a timer | |
| Stop timer and save entry | |
| Discard running timer |
Projects (5 tools)
Tool | Read-only | Description |
| ✓ | List projects |
| ✓ | Get project by ID |
| Create project | |
| Update project | |
| Delete project |
Expenses (5 tools)
Tool | Read-only | Description |
| ✓ | List expenses |
| ✓ | Get expense by ID |
| Create expense | |
| Update expense | |
| Delete expense |
Payments (5 tools)
Tool | Read-only | Description |
| ✓ | List invoice payments |
| ✓ | Get payment by ID |
| Record payment | |
| Update payment | |
| Delete payment |
Bills (10 tools)
Tool | Read-only | Description |
| ✓ | List bills |
| ✓ | Get bill by ID |
| ✓ | List bill payments |
| ✓ | Get bill payment by ID |
| Create bill | |
| Archive bill | |
| Delete bill | |
| Record bill payment | |
| Update bill payment | |
| Delete bill payment |
Vendors (5 tools)
Tool | Read-only | Description |
| ✓ | List vendors |
| ✓ | Get vendor by ID |
| Create vendor | |
| Update vendor | |
| Delete vendor |
Reports (3 tools — all read-only)
Tool | Description |
| Profit & loss report |
| Payments collected report |
| Tax summary report |
Additional Tools
Category | Count | Read-only | Description |
Credit Notes | 5 | 2 | Create and manage credit notes |
Expense Categories | 2 | 2 | Browse expense categories |
Items | 4 | 2 | Product/service catalog |
Journal Entries | 2 | 1 | Manual accounting entries |
Other Income | 5 | 2 | Non-invoice income tracking |
Payment Options | 3 | 2 | Payment gateway settings |
Services | 5 | 3 | Billable service types incl. rate get/set |
Tasks | 5 | 2 | Project task management |
User | 1 | 1 | Current user info |
Callbacks | 7 | 2 | Webhook management |
Self-Hosted Setup
You can also run the MCP server locally with your own FreshBooks OAuth application. This is optional — most users should use the hosted service above.
Note: FreshBooks requires HTTPS for all OAuth callback URLs, including localhost. See Local HTTPS Setup below.
1. Get FreshBooks Credentials
Create a new application
Set redirect URI to:
https://freshbooks.goodsamsoftware.com/callbackNote your Client ID and Client Secret
2. Install and Configure
npm install @goodsamsoftware/freshbooks-mcpAdd to your Claude Desktop config:
{
"mcpServers": {
"freshbooks": {
"command": "npx",
"args": ["@goodsamsoftware/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. After authorizing, copy the code from the hosted callback page and paste it back to Claude.
Environment Variables
Variable | Required | Description |
| Yes | OAuth client ID |
| Yes | OAuth client secret |
| Yes | OAuth redirect URI |
| No | Path for token storage |
| No | Logging level (debug, info, warn, error) |
Advanced: Local HTTPS Setup
For a local callback URL, set up trusted certificates with mkcert:
Windows: winget install FiloSottile.mkcert
macOS: brew install mkcert
Linux: See mkcert installation
mkcert -install
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1Then set your redirect URI to https://localhost:3000/callback in FreshBooks.
Development
npm install # Install dependencies
npm run dev # Run in development mode
npm test # Run tests
npm run test:coverage # Run with coverage report
npm run typecheck # Type check
npm run build # Build for productionTesting
1,613 tests across 93 test files
100% code coverage requirement
Mock factories for all FreshBooks entities
Architecture
src/
├── server.ts # MCP server entry point
├── auth/ # OAuth2 authentication
├── client/ # FreshBooks SDK wrapper
├── errors/ # Error normalization
├── tools/ # MCP tool implementations (22 categories)
│ ├── time-entry/ # Time tracking
│ ├── timer/ # Timer management
│ ├── invoice/ # Invoicing
│ ├── client/ # Client management
│ ├── project/ # Projects
│ ├── expense/ # Expenses
│ ├── bill/ # Bills
│ └── ... # 15 more categories
└── config/ # ConfigurationDocumentation
API Reference - Complete tool documentation
Authentication Setup - OAuth configuration
Examples - Workflow examples
License
MIT License — see LICENSE for details.
Credits
Available Tools
4 toolsauth_exchange_codeA
Exchange an OAuth authorization code for access and refresh tokens, completing the FreshBooks connection.
WHEN TO USE:
Immediately after the user visits the auth_get_url link and is redirected with a code
Only call once per code — codes expire quickly (typically 60 seconds)
REQUIRED:
code (string): The authorization code from the FreshBooks redirect URL. Example: "eyJhbGci..."
state (string): The state value returned by auth_get_url — must match to prevent CSRF. Example: "abc123xyz"
RETURNS: { success: true, userId, accountId, businessId, email, expiresAt } Tokens are stored locally; all subsequent tool calls use them automatically.
ERRORS:
Expired or invalid code → restart with auth_get_url
State mismatch → CSRF protection triggered → restart with auth_get_url
Inputs: code (required), state (required).
auth_get_urlA
Generate an OAuth 2.0 authorization URL and a CSRF state token for the FreshBooks sign-in flow.
WHEN TO USE:
auth_status returns { connected: false }
User says "connect my FreshBooks account" or "sign in to FreshBooks"
Re-authenticating after a revoked or expired session
TAKES NO ARGUMENTS.
RETURNS: { url: "https://auth.freshbooks.com/oauth/authorize?...", state: "" }
WORKFLOW:
Call auth_get_url → share the url with the user
User visits the URL, authorizes, and is redirected — the redirect URL contains code and state query params
User pastes the code and state back → call auth_exchange_code with both values
Inputs: no named parameters.
auth_revokeA
Revoke the current FreshBooks OAuth session and delete all stored tokens.
WHEN TO USE:
User says "disconnect FreshBooks", "sign out", or "remove my FreshBooks connection"
Switching to a different FreshBooks account — revoke first, then use auth_get_url for the new account
Security: clear stored credentials from this machine
TAKES NO ARGUMENTS.
RETURNS: { success: true, message: "Authentication revoked successfully" }
NOTE: After calling this tool, all accounting and time-tracking tools will return auth errors until a new OAuth session is established via auth_get_url → auth_exchange_code.
Inputs: no named parameters.
auth_statusA
Check whether FreshBooks is connected and return the active session details.
WHEN TO USE:
Call first in any workflow before using accounting or time-tracking tools
User asks "am I connected to FreshBooks?", "what account is linked?"
Diagnose why a tool returned an auth error
TAKES NO ARGUMENTS — safe to call anytime.
RETURNS (connected session): { connected: true, userId, accountId, businessId, email, expiresAt }
accountId and businessId are the IDs to pass to accounting and time-tracking tools
RETURNS (no session or expired token): { connected: false }
NEXT STEPS:
If connected: false → call auth_get_url to start OAuth
If connected: true → use accountId/businessId with all other tools
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool maps to a distinct OAuth lifecycle step: checking status, generating an authorization URL, exchanging the callback code, and revoking the session. There is no meaningful overlap between the tools.
All tools share the auth_ prefix and use snake_case, which creates a clear family. The minor inconsistency is that auth_status is noun-like while auth_get_url, auth_exchange_code, and auth_revoke are action-oriented.
Four tools is well-scoped for the authentication functionality being exposed. Each tool is necessary for completing or managing the FreshBooks OAuth connection, and none are redundant.
The auth lifecycle itself is complete, but the descriptions repeatedly mention accounting and time-tracking tools that do not exist in this server. After connecting, an agent has no actual FreshBooks accounting operations to call, leaving a significant dead end.
Maintenance
Related MCP Connectors
Invoicing, expenses, accounting analytics. OAuth 2.1 dynamic client registration, no API key.
The integration hub for your CRM, field service and accounting apps: integrations and AI agents.
Track time, manage clients and projects, review timesheets, and create invoices with OAuth.
Track expenses, budgets, balances, transfers, and multi-currency reports with OAuth-secured tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAutomates FreshBooks invoicing and time tracking through Claude, allowing users to send invoices, list invoices, log billable hours, and get financial insights via natural language commands.2-
- AlicenseBqualityDmaintenanceProduction-grade MCP server for FreshBooks. 25 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, and financial reports. OAuth2 with automatic token refresh.253MIT
- AlicenseNot gradedqualityDmaintenanceIntegrates with the sevdesk German accounting API, providing 76 tools for full CRUD operations across contacts, invoices, vouchers, orders, credit notes, bank accounts, transactions, parts, tags, addresses, and communication ways.6ISC
- AlicenseNot gradedqualityDmaintenanceProvides 54 tools across 10 categories for Wave Accounting, enabling invoicing, customer management, products, transactions, bills, estimates, taxes, businesses, and financial reporting through Wave's GraphQL API.16 npm1ISC