mcp-freshbooks
The mcp-freshbooks server is a production-grade MCP server providing comprehensive FreshBooks accounting integration through 53 tools across the following areas:
๐ Authentication & Identity
OAuth2 authentication flow with automatic token refresh
Retrieve current user identity, account ID, and business info
๐งพ Invoice Management
Create, list (with filters by status/customer), view, update, send, and delete invoices
Manage recurring invoices
๐ฅ Client Management
Full CRUD operations on client records with search by name/organization
Get summarized client information
๐ Estimates
Create, list, retrieve, update, and send estimates
Convert estimates directly into invoices
๐ธ Expense Tracking
Create, list, retrieve, update, and delete expenses with category, vendor, and notes
List expense categories
๐ณ Payments
List all payments and record new payments against invoices
Supports Check, Credit, Cash, Bank Transfer, Credit Card, PayPal, ACH, and more
โฑ๏ธ Time Tracking
Create, list, retrieve, update, and delete time entries with project/client association and billable flag
Identify unbilled time for invoicing
๐ Project Management
Create, list, retrieve, and update projects with billing method (hourly/fixed), budget, and due date
๐ Financial Reports
Generate Profit & Loss, Tax Summary, Payments Collected, Accounts Aging, and Balance Sheet reports with optional date ranges
โ๏ธ Smart Workflow Automation
Convert estimates to invoices, find overdue invoices, identify unbilled time, and get client summaries
Manage items/inventory and tax rates
mcp-freshbooks
Production-grade MCP server for FreshBooks โ 53 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, financial reports, and smart workflows.
Features
53 tools covering the full FreshBooks accounting workflow
Smart workflow tools โ convert estimates to invoices, invoice unbilled time, find overdue clients, get full client summaries
5 financial reports โ P&L, tax summary, accounts aging, balance sheet, payments collected
OAuth2 authentication with automatic token refresh
Clean output โ summarized lists, formatted details
Production-grade error handling and rate limit awareness
Zero cost โ uses FreshBooks free developer program
Related MCP server: Wave MCP Server
Tools
Category | Tools | Count |
Auth |
| 3 |
Invoices |
| 6 |
Recurring |
| 3 |
Clients |
| 5 |
Estimates |
| 5 |
Expenses |
| 5 |
Payments |
| 3 |
Time Tracking |
| 5 |
Projects |
| 4 |
Reports |
| 5 |
Items |
| 2 |
Categories |
| 1 |
Taxes |
| 1 |
Workflows |
| 5 |
Quick Start
1. Install
pip install mcp-freshbooksOr from source:
git clone https://github.com/AlexlaGuardia/mcp-freshbooks.git
cd mcp-freshbooks
pip install .2. Get FreshBooks API Credentials
Sign up at freshbooks.com/pages/developer-signup
Create an OAuth app in the developer portal
Set redirect URI to
https://localhost:8555/callbackCopy your Client ID and Client Secret
3. Configure
export FRESHBOOKS_CLIENT_ID=your_client_id
export FRESHBOOKS_CLIENT_SECRET=your_client_secret
export FRESHBOOKS_REDIRECT_URI=https://localhost:8555/callback4. Add to Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"freshbooks": {
"command": "mcp-freshbooks",
"env": {
"FRESHBOOKS_CLIENT_ID": "your_client_id",
"FRESHBOOKS_CLIENT_SECRET": "your_client_secret",
"FRESHBOOKS_REDIRECT_URI": "https://localhost:8555/callback"
}
}
}
}5. Authenticate
Use the freshbooks_authenticate tool on first use. It will give you a URL to open in your browser. After authorizing, tokens are saved to ~/.mcp-freshbooks/tokens.json and auto-refresh.
Usage Examples
Who owes me money?
Use get_overdue_invoices to see all past-due clients and total outstandingConvert a proposal to an invoice:
Use convert_estimate_to_invoice to turn estimate 456 into a ready-to-send invoiceFind unbilled work:
Use get_unbilled_time to find time entries not yet on any invoiceCheck profitability:
Get the profit and loss report for Q1 2026Track time:
Create a 2-hour time entry for project 789 with note "API integration work"Architecture
src/mcp_freshbooks/
โโโ server.py # MCP server with 47 tool definitions
โโโ client.py # FreshBooks API client (httpx async)
โโโ auth.py # OAuth2 flow + token persistenceThe server uses the MCP Python SDK with FastMCP for clean tool registration. All API calls go through the async client with automatic token refresh.
Requirements
Python 3.10+
FreshBooks account (free trial works for development)
FreshBooks OAuth app credentials
License
MIT
Available Tools
25 toolscreate_clientC
Create a new client.
Inputs: email (required), first_name, last_name, organization, +2 more. Returns: result
create_estimateC
Create an estimate. Lines format same as invoices.
Inputs: customer_id (required), lines (required), currency_code, notes. Returns: result
create_expenseC
Create a new expense. Amount as string (e.g. '150.00'). Date as YYYY-MM-DD.
Inputs: category_id (required), staff_id (required), amount (required), date (required), +4 more. Returns: result
create_invoiceC
Create a new invoice. Lines format: [{"name": "Service", "description": "...", "qty": 1, "unit_cost": {"amount": "100.00", "code": "USD"}}]
Inputs: customer_id (required), lines (required), due_offset_days, currency_code, +2 more. Returns: result
create_paymentC
Record a payment against an invoice. Amount as string. Date as YYYY-MM-DD. Types: Check, Credit, Cash, Bank Transfer, Credit Card, PayPal, ACH, Other.
Inputs: invoice_id (required), amount (required), date (required), payment_type, +2 more. Returns: result
create_projectC
Create a project. project_type: hourly_rate or fixed_price. billing_method: business_rate, project_rate, service_rate, team_member_rate.
Inputs: title (required), client_id, project_type, billing_method, +3 more. Returns: result
create_time_entryC
Create a time entry. started_at as ISO8601 (e.g. '2026-03-20T09:00:00'). Duration in seconds.
Inputs: started_at (required), duration_seconds (required), client_id, project_id, +2 more. Returns: result
delete_invoiceB
Delete an invoice permanently.
Inputs: invoice_id (required). Returns: result
freshbooks_authenticateA
Start FreshBooks OAuth2 authentication. Returns a URL to open in your browser. After authorizing, tokens are saved automatically.
Inputs: no named parameters. Returns: result
freshbooks_authenticate_with_codeA
Complete authentication with an authorization code (if callback server isn't used). Paste the code from the redirect URL.
Inputs: code (required). Returns: result
freshbooks_whoamiA
Get the current authenticated user's identity, account ID, and business info.
Inputs: no named parameters. Returns: result
get_clientB
Get full details of a specific client.
Inputs: client_id (required). Returns: result
get_expenseB
Get full details of a specific expense.
Inputs: expense_id (required). Returns: result
get_invoiceB
Get full details of a specific invoice including line items.
Inputs: invoice_id (required). Returns: result
get_reportC
Get a financial report. Types: profitloss_entity, taxsummary, payments_collected. Dates as YYYY-MM-DD.
Inputs: report_type (required), start_date, end_date. Returns: result
list_clientsC
List clients. Optional search by name or organization.
Inputs: page, per_page, search. Returns: result
list_estimatesD
List estimates.
Inputs: page, per_page. Returns: result
list_expensesB
List expenses with optional client filter.
Inputs: page, per_page, client_id. Returns: result
list_invoicesC
List invoices with optional filters. Status: draft, sent, viewed, outstanding, paid.
Inputs: page, per_page, status, customer_id. Returns: result
list_paymentsC
List all payments.
Inputs: page, per_page. Returns: result
list_projectsD
List projects.
Inputs: page, per_page. Returns: result
list_time_entriesD
List time entries.
Inputs: page, per_page. Returns: result
send_invoiceB
Send an invoice by email to the client.
Inputs: invoice_id (required). Returns: result
update_clientC
Update a client. Pass any writable client fields.
Inputs: client_id (required), updates (required). Returns: result
update_invoiceC
Update an invoice. Pass any writable invoice fields as updates dict.
Inputs: invoice_id (required), updates (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 25 tools
Every tool has a clearly distinct purpose targeting specific resources and actions in the FreshBooks domain. Tools like create_client, get_client, update_client, and list_clients form a coherent set around clients, with no overlap or ambiguity between different resource types (e.g., invoices, expenses, time entries). The descriptions reinforce distinct operations.
Tool names follow a highly consistent verb_noun pattern throughout, using snake_case uniformly. All CRUD operations use create_, get_, update_, delete_, or list_ prefixes, and domain-specific actions like send_invoice and freshbooks_authenticate maintain clear, predictable naming. No deviations or mixed conventions are present.
With 25 tools, the count is borderline high for a single server, potentially feeling heavy. However, given FreshBooks' broad domain (clients, invoices, expenses, projects, time tracking, authentication, reports), the tools cover many aspects, so it's not extreme but may overwhelm agents with its scope.
The tool set provides comprehensive coverage for core FreshBooks workflows, including CRUD operations for clients, invoices, expenses, projects, and time entries, plus authentication, reporting, and actions like sending invoices. Minor gaps exist, such as no update/delete for expenses or projects, but agents can work around these with the available tools.
Related MCP Connectors
Free hosted MCP for invoices, estimates, clients, items and PDFs. OAuth authorization required.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
MCP server for Codat โ companies, connections, invoices, bills and financial statements.
Unofficial remote MCP server for Less Annoying CRM: OAuth 2.1, read-only grants, 10 tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceOfficial MCP server for Timebook (usetimebook.com) โ time tracking, invoicing, and bookkeeping for freelancers and solo LLCs. Manage clients and projects, start/stop timers, and log, update, and delete time entries. Stdio via the @squidcode/timebook npm CLI; a hosted OAuth endpoint also exists at https://usetimebook.com/mcp.12116 npm2MIT
- AlicenseNot gradedqualityDmaintenanceComprehensive MCP server for Wave Accounting, providing 45+ tools across invoicing, customers, products, transactions, bills, estimates, taxes, and financial reporting, plus 17 pre-built UI workflows.5MIT
- FlicenseNot gradedqualityCmaintenanceAn MCP server that connects Claude to FreshBooks, enabling reading and management of invoices, clients, expenses, projects, and time entries via natural language.1-
- FlicenseNot gradedqualityDmaintenanceAn MCP server for the FreshBooks API that lets Claude read and manage invoices, clients, expenses, projects, services, payments, and time entries.-