MCP FreshBooks
About
Production-grade MCP server for FreshBooks — 25 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, and financial reports. OAuth2 with automatic token refresh.
Details
- Author
- AlexlaGuardia
- Downloads
- 294
- Categories
- Other
Jump to
- 25 tools covering the full FreshBooks accounting workflow
- OAuth2 authentication with automatic token refresh
- Clean, summarized list and formatted detail outputs
- Production-grade error handling and rate limit awareness
- Zero cost – uses FreshBooks free developer program
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
MCP FreshBooksCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install the package via pip install mcp-freshbooks, then obtain FreshBooks OAuth credentials by signing up at the developer portal. Set the environment variables FRESHBOOKS_CLIENT_ID, FRESHBOOKS_CLIENT_SECRET, and FRESHBOOKS_REDIRECT_URI. Add the server to your claude_desktop_config.json under mcpServers. On first use, invoke the freshbooks_authenticate tool to initiate the OAuth2 flow; tokens are saved to ~/.mcp-freshbooks/tokens.json and refresh automatically.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp freshbooks": {
"freshbooks": {
"command": "mcp-freshbooks",
"env": {
"FRESHBOOKS_CLIENT_ID": "your_client_id",
"FRESHBOOKS_CLIENT_SECRET": "your_client_secret",
"FRESHBOOKS_REDIRECT_URI": "https://localhost:8555/callback"
}
}
}
}
}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"
}
}
}mcp-freshbooks
Production-grade MCP server for FreshBooks — 25 tools for invoices, clients, expenses, payments, time tracking, projects, estimates, and financial reports.
Features
- 25 tools covering the full FreshBooks accounting workflow
- 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
Tools
| Category | Tools | Description |
|----------|-------|-------------|
| Auth | freshbooks_authenticate, freshbooks_authenticate_with_code, freshbooks_whoami | OAuth2 flow + identity |
| Invoices | list_invoices, get_invoice, create_invoice, update_invoice, send_invoice, delete_invoice | Full invoice lifecycle |
| Clients | list_clients, get_client, create_client, update_client | Client management |
| Expenses | list_expenses, get_expense, create_expense | Expense tracking |
| Payments | list_payments, create_payment | Payment recording |
| Time Tracking | list_time_entries, create_time_entry | Time entry management |
| Projects | list_projects, create_project | Project management |
| Estimates | list_estimates, create_estimate | Estimate creation |
| Reports | get_report | Profit & loss, tax summary, payments collected |
Quick Start
1. Install
pip install mcp-freshbooks
Or from source:
git clone https://github.com/AlexlaGuardia/mcp-freshbooks.git
cd mcp-freshbooks
pip install .
2. Get FreshBooks API Credentials
1. Sign up at freshbooks.com/pages/developer-signup
2. Create an OAuth app in the developer portal
3. Set redirect URI to https://localhost:8555/callback
4. Copy 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/callback
4. 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
List overdue invoices:
Use list_invoices with status "outstanding"
Create and send an invoice:
Create an invoice for client 12345 with a line item for "Web Development" at $1,500, then send it
Check profitability:
Get the profit and loss report for Q1 2026
Track time:
Create a 2-hour time entry for project 789 with note "API integration work"
Architecture
src/mcp_freshbooks/
├── server.py # MCP server with 25 tool definitions
├── client.py # FreshBooks API client (httpx async)
└── auth.py # OAuth2 flow + token persistence
The 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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
