Yes, Freshbooks is free to use.

How do I install Freshbooks?

Freshbooks is a local plugin. Install it using npm package: @chrischall/freshbooks-mcp and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

Is Freshbooks safe to use?

Freshbooks scored 7/10 (moderate risk) in MCP Marketplace's automated security scan. It has 1 high or critical finding to review. It's listed, but review the security report on this page before installing.

What AI apps work with Freshbooks?

Freshbooks uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Freshbooks MCP Server

by Chris Hall

Developer ToolsModerate7.0LocalNew

Free

FreshBooks invoicing for Claude — invoices, clients, estimates, and payments

About

FreshBooks invoicing for Claude — invoices, clients, estimates, and payments

Security Report

7.0

Moderate7.0Moderate Risk

This is a well-architected FreshBooks MCP server with proper OAuth2 authentication, secure token handling, and good input validation through Zod. The codebase demonstrates strong security practices including path traversal protection, permission-aware error messages, and confirm-gated mutations. Minor code quality observations around broad exception handling do not materially impact security. Supply chain analysis found 2 known vulnerabilities in dependencies (0 critical, 1 high severity). Package verification found 1 issue.

5 files analyzed · 8 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

What You'll Need

Set these up before or after installing:

OAuth client ID from my.freshbooks.com/#/developerOptional

Environment variable: FRESHBOOKS_CLIENT_ID

OAuth client secretRequired

Environment variable: FRESHBOOKS_CLIENT_SECRET

OAuth refresh token from the one-time bootstrap (rotates on every use)Required

Environment variable: FRESHBOOKS_REFRESH_TOKEN

Registered redirect URI; required on refresh calls too (default https://localhost/callback)Optional

Environment variable: FRESHBOOKS_REDIRECT_URI

Path for the rotating-refresh-token store (default ~/.freshbooks-mcp/session.json)Optional

Environment variable: FRESHBOOKS_TOKEN_STORE

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "io-github-chrischall-freshbooks-mcp": {
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your-freshbooks-client-id-here",
        "FRESHBOOKS_TOKEN_STORE": "your-freshbooks-token-store-here",
        "FRESHBOOKS_REDIRECT_URI": "your-freshbooks-redirect-uri-here",
        "FRESHBOOKS_CLIENT_SECRET": "your-freshbooks-client-secret-here",
        "FRESHBOOKS_REFRESH_TOKEN": "your-freshbooks-refresh-token-here"
      },
      "args": [
        "-y",
        "@chrischall/freshbooks-mcp"
      ],
      "command": "npx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

freshbooks-mcp

MCP server for FreshBooks — invoices, clients, estimates and payments, exposed to Claude as typed tools.

This project was developed and is maintained by AI (Claude Code). Use at your own discretion.

Install

npm install -g @chrischall/freshbooks-mcp

Setup

FreshBooks is OAuth2 only — there is no API key and no personal access token, so a one-time browser authorization is required.

Register an app at https://my.freshbooks.com/#/developer. The redirect URI must be HTTPS with no query string; https://localhost works and never needs to resolve.
Note the Client ID and Client Secret.
Run the one-time bootstrap to obtain a refresh token — see skills/freshbooks-curl, which ships the bootstrap script.
Configure:

FRESHBOOKS_CLIENT_ID=...
FRESHBOOKS_CLIENT_SECRET=...
FRESHBOOKS_REFRESH_TOKEN=...       # from the bootstrap
FRESHBOOKS_REDIRECT_URI=https://localhost   # optional; must match what you registered
FRESHBOOKS_TOKEN_STORE=~/.freshbooks-mcp/session.json   # optional

⚠️ Refresh tokens rotate

FreshBooks issues a new refresh token on every refresh and immediately invalidates the old one. This server persists each rotation to FRESHBOOKS_TOKEN_STORE (mode 0600) before the refresh is considered complete, and prefers the stored token over the environment value — the stored one has rotated past it.

Two consequences worth knowing:

Do not point two tools at the same store. The MCP server and the freshbooks-curl skill keep separate state files on purpose; sharing one makes them spend each other's tokens and locks both out.
If the store is lost, re-run the bootstrap. A spent refresh token cannot be recovered.

Changing FRESHBOOKS_REFRESH_TOKEN to a freshly bootstrapped value is detected and adopted, so re-bootstrapping is the supported recovery path.

Tools

Tool	Purpose
`freshbooks_get_identity`	Resolve accountId / businessId / businessUuid
`freshbooks_list_invoices` / `freshbooks_get_invoice`	Browse and fetch invoices
`freshbooks_list_clients` / `freshbooks_get_client`	Browse and fetch clients
`freshbooks_list_estimates` / `freshbooks_get_estimate`	Browse and fetch estimates
`freshbooks_list_payments` / `freshbooks_get_payment`	Browse and fetch payments
`freshbooks_list_items` / `freshbooks_get_item`	Browse and fetch catalogue items
`freshbooks_create_client`	Create a client — confirm-gated
`freshbooks_create_invoice`	Create an invoice — confirm-gated
`freshbooks_update_invoice`	Update an invoice — confirm-gated
`freshbooks_record_payment`	Record a payment against an invoice — confirm-gated
`freshbooks_list_expenses` / `freshbooks_get_expense`	Browse and fetch expenses
`freshbooks_list_expense_categories`	Categories supplying `categoryid` for new expenses
`freshbooks_create_expense`	Record an expense — confirm-gated
`freshbooks_list_projects` / `freshbooks_get_project`	Projects (businessId-keyed)
`freshbooks_create_project`	Create a project — confirm-gated
`freshbooks_list_time_entries`	Tracked time, with `total_logged` / `total_unbilled`
`freshbooks_create_time_entry`	Log time in seconds — confirm-gated
`freshbooks_list_services`	Billable work types for projects and time entries
`freshbooks_list_records` / `freshbooks_get_record`	Generic accessor for the accounting long tail (taxes, credit notes, invoice profiles, tasks, staff, gateways, bills, bill vendors, bill payments, other income)

Confirm-gated means the tool makes no network call unless confirm: true is passed; without it you get a dry-run preview of exactly what would be sent.

Writes require an owner/admin accounting account

FreshBooks separates the role you hold on a business from the role you hold on an accounting account. You can own a business that has no accounting account (account_id: null) while being only a client on the account you can actually see — in which case reads succeed and every write returns 403 Permission Denied, even though your OAuth token carries all the :write scopes.

freshbooks_get_identity reports accountRole and businessRole so this is visible up front. If accountRole is client, the invoicing write tools will not work against that account — that is an account permission, not a configuration problem.

Two things the API reports misleadingly

total counts records you may not be able to read. Expenses reported total: 16 while returning zero rows. List results attach a note when that happens, so it reads as a permission boundary rather than an empty account.
Projects and time tracking are keyed by businessId, not accountId, and paginate under a meta block instead of flat page/pages/total. They also work on a business with no accounting account at all.

The three identifiers

FreshBooks hands out three non-interchangeable ids, and using the wrong one returns a bare 404 that reads like a missing record:

Identifier	Used by
`accountId` (alphanumeric)	`/accounting/account/…`, `/payments/account/…`
`businessId` (integer)	`/projects/business/…`, `/timetracking/business/…`
`businessUuid` (UUID)	`/accounting/businesses/…`