Skip to main content
Glama
mcp-freshbooks

mcp-freshbooks

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

freshbooks_authenticate, freshbooks_authenticate_with_code, freshbooks_whoami

3

Invoices

list_invoices, get_invoice, create_invoice, update_invoice, send_invoice, delete_invoice

6

Recurring

list_recurring_invoices, create_recurring_invoice, update_recurring_invoice

3

Clients

list_clients, get_client, create_client, update_client, delete_client

5

Estimates

list_estimates, get_estimate, create_estimate, update_estimate, send_estimate

5

Expenses

list_expenses, get_expense, create_expense, update_expense, delete_expense

5

Payments

list_payments, get_payment, create_payment

3

Time Tracking

list_time_entries, get_time_entry, create_time_entry, update_time_entry, delete_time_entry

5

Projects

list_projects, get_project, create_project, update_project

4

Reports

get_profit_loss, get_tax_summary, get_accounts_aging, get_balance_sheet, get_payments_collected

5

Items

list_items, create_item

2

Categories

list_expense_categories

1

Taxes

list_taxes

1

Workflows

convert_estimate_to_invoice, get_overdue_invoices, get_unbilled_time, invoice_from_time, client_summary

5

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

Who owes me money?

Use get_overdue_invoices to see all past-due clients and total outstanding

Convert a proposal to an invoice:

Use convert_estimate_to_invoice to turn estimate 456 into a ready-to-send invoice

Find unbilled work:

Use get_unbilled_time to find time entries not yet on any invoice

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 47 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

Available Tools

25 tools
create_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

    B3/5.0

    Scored across 25 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Official 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.
      12
      116 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Comprehensive 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.
      5
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that connects Claude to FreshBooks, enabling reading and management of invoices, clients, expenses, projects, and time entries via natural language.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for the FreshBooks API that lets Claude read and manage invoices, clients, expenses, projects, services, payments, and time entries.
      -