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

Sign up at freshbooks.com/pages/developer-signup
Create an OAuth app in the developer portal
Set redirect URI to https://localhost:8555/callback
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.