Skip to main content
Glama

FreshBooks MCP by Good Samaritan Software

License: MIT TypeScript Tests freshbooks-mcp MCP server

Manage your FreshBooks in plain English from Claude or ChatGPT. FreshBooks MCP is a fully hosted service — no local install, no API keys to manage, one OAuth sign-in to your FreshBooks account. 41 of the 92 tools are read-only by default; write operations surface a confirmation step in your AI client before any data changes.

Get started →  ·  Documentation  ·  Pricing — from $29/mo

Currently available in the United States. International waitlist available at the link above.


What you can do

92 tools spanning invoices, clients, expenses, time tracking, projects, payments, vendors, bills, and reports — with 41 read-only tools for safe lookups and 51 write tools for full account management.

Example prompts:

  • "Show me all unpaid invoices over $500"

  • "Create an invoice for Acme Corp for $1,500 due in 30 days"

  • "What's my profit and loss for this year?"

  • "Log 2 hours on the Website Redesign project"

  • "Start a timer for this client meeting"

  • "Record a $45 office supplies expense"

  • "List all vendors I've paid this quarter"


Related MCP server: mcp-freshbooks

The fastest path: subscribe, connect FreshBooks, paste your config into your AI client.

Claude (Desktop, Code, Web)

  1. Go to freshbooks.goodsamsoftware.com, create an account, and connect your FreshBooks account. Copy your API key from the dashboard.

  2. Add to your Claude Desktop config (claude_desktop_config.json) or Claude Code project config (.mcp.json):

{
  "mcpServers": {
    "freshbooks": {
      "command": "npx",
      "args": ["mcp-remote", "https://freshbooks.goodsamsoftware.com/api/mcp", "--header", "Authorization:Bearer YOUR_API_KEY"]
    }
  }
}

ChatGPT

  1. In ChatGPT, go to Settings → Connectors → Add connector.

  2. Enter the MCP server URL: https://freshbooks.goodsamsoftware.com/api/mcp

  3. Complete the OAuth flow to connect your FreshBooks account.

Other MCP Clients (Cursor, Windsurf, Continue, Cline, etc.)

Use the same mcp-remote configuration shown above, substituting your client's config location.


Available Tools (92 total)

Invoices (6 tools)

Tool

Read-only

Description

invoice_list

✓

List invoices with filters

invoice_single

✓

Get invoice by ID

invoice_share_link

✓

Get shareable payment link

invoice_create

Create invoice

invoice_update

Update invoice

invoice_delete

Delete invoice

Clients (5 tools)

Tool

Read-only

Description

client_list

✓

List clients

client_single

✓

Get client by ID

client_create

Create client

client_update

Update client

client_delete

Delete client

Time Tracking (9 tools)

Tool

Read-only

Description

timeentry_list

✓

List time entries with filters

timeentry_single

✓

Get time entry by ID

timer_current

✓

Get running timer

timeentry_create

Create time entry

timeentry_update

Update time entry

timeentry_delete

Delete time entry

timer_start

Start a timer

timer_stop

Stop timer and save entry

timer_discard

Discard running timer

Projects (5 tools)

Tool

Read-only

Description

project_list

✓

List projects

project_single

✓

Get project by ID

project_create

Create project

project_update

Update project

project_delete

Delete project

Expenses (5 tools)

Tool

Read-only

Description

expense_list

✓

List expenses

expense_single

✓

Get expense by ID

expense_create

Create expense

expense_update

Update expense

expense_delete

Delete expense

Payments (5 tools)

Tool

Read-only

Description

payment_list

✓

List invoice payments

payment_single

✓

Get payment by ID

payment_create

Record payment

payment_update

Update payment

payment_delete

Delete payment

Bills (10 tools)

Tool

Read-only

Description

bill_list

✓

List bills

bill_single

✓

Get bill by ID

billpayment_list

✓

List bill payments

billpayment_single

✓

Get bill payment by ID

bill_create

Create bill

bill_archive

Archive bill

bill_delete

Delete bill

billpayment_create

Record bill payment

billpayment_update

Update bill payment

billpayment_delete

Delete bill payment

Vendors (5 tools)

Tool

Read-only

Description

billvendor_list

✓

List vendors

billvendor_single

✓

Get vendor by ID

billvendor_create

Create vendor

billvendor_update

Update vendor

billvendor_delete

Delete vendor

Reports (3 tools — all read-only)

Tool

Description

report_profit_loss

Profit & loss report

report_payments_collected

Payments collected report

report_tax_summary

Tax summary report

Additional Tools

Category

Count

Read-only

Description

Credit Notes

5

2

Create and manage credit notes

Expense Categories

2

2

Browse expense categories

Items

4

2

Product/service catalog

Journal Entries

2

1

Manual accounting entries

Other Income

5

2

Non-invoice income tracking

Payment Options

3

2

Payment gateway settings

Services

5

3

Billable service types incl. rate get/set

Tasks

5

2

Project task management

User

1

1

Current user info

Callbacks

7

2

Webhook management


Self-Hosted Setup

You can also run the MCP server locally with your own FreshBooks OAuth application. This is optional — most users should use the hosted service above.

Note: FreshBooks requires HTTPS for all OAuth callback URLs, including localhost. See Local HTTPS Setup below.

1. Get FreshBooks Credentials

  1. Go to FreshBooks Developer Portal

  2. Create a new application

  3. Set redirect URI to: https://freshbooks.goodsamsoftware.com/callback

  4. Note your Client ID and Client Secret

2. Install and Configure

npm install @goodsamsoftware/freshbooks-mcp

Add to your Claude Desktop config:

{
  "mcpServers": {
    "freshbooks": {
      "command": "npx",
      "args": ["@goodsamsoftware/freshbooks-mcp"],
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your-client-id",
        "FRESHBOOKS_CLIENT_SECRET": "your-client-secret",
        "FRESHBOOKS_REDIRECT_URI": "https://freshbooks.goodsamsoftware.com/callback"
      }
    }
  }
}

3. Authenticate

Ask Claude: "Connect me to FreshBooks"

Claude will guide you through OAuth. After authorizing, copy the code from the hosted callback page and paste it back to Claude.

Environment Variables

Variable

Required

Description

FRESHBOOKS_CLIENT_ID

Yes

OAuth client ID

FRESHBOOKS_CLIENT_SECRET

Yes

OAuth client secret

FRESHBOOKS_REDIRECT_URI

Yes

OAuth redirect URI

FRESHBOOKS_TOKEN_PATH

No

Path for token storage

LOG_LEVEL

No

Logging level (debug, info, warn, error)

Advanced: Local HTTPS Setup

For a local callback URL, set up trusted certificates with mkcert:

Windows: winget install FiloSottile.mkcert macOS: brew install mkcert Linux: See mkcert installation

mkcert -install
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1

Then set your redirect URI to https://localhost:3000/callback in FreshBooks.


Development

npm install          # Install dependencies
npm run dev          # Run in development mode
npm test             # Run tests
npm run test:coverage  # Run with coverage report
npm run typecheck    # Type check
npm run build        # Build for production

Testing

  • 1,613 tests across 93 test files

  • 100% code coverage requirement

  • Mock factories for all FreshBooks entities

Architecture

src/
├── server.ts             # MCP server entry point
├── auth/                 # OAuth2 authentication
├── client/               # FreshBooks SDK wrapper
├── errors/               # Error normalization
├── tools/                # MCP tool implementations (22 categories)
│   ├── time-entry/       # Time tracking
│   ├── timer/            # Timer management
│   ├── invoice/          # Invoicing
│   ├── client/           # Client management
│   ├── project/          # Projects
│   ├── expense/          # Expenses
│   ├── bill/             # Bills
│   └── ...               # 15 more categories
└── config/               # Configuration

Documentation

License

MIT License — see LICENSE for details.

Credits

Available Tools

4 tools
auth_exchange_codeA

Exchange an OAuth authorization code for access and refresh tokens, completing the FreshBooks connection.

WHEN TO USE:

  • Immediately after the user visits the auth_get_url link and is redirected with a code

  • Only call once per code — codes expire quickly (typically 60 seconds)

REQUIRED:

  • code (string): The authorization code from the FreshBooks redirect URL. Example: "eyJhbGci..."

  • state (string): The state value returned by auth_get_url — must match to prevent CSRF. Example: "abc123xyz"

RETURNS: { success: true, userId, accountId, businessId, email, expiresAt } Tokens are stored locally; all subsequent tool calls use them automatically.

ERRORS:

  • Expired or invalid code → restart with auth_get_url

  • State mismatch → CSRF protection triggered → restart with auth_get_url

Inputs: code (required), state (required).

auth_get_urlA

Generate an OAuth 2.0 authorization URL and a CSRF state token for the FreshBooks sign-in flow.

WHEN TO USE:

  • auth_status returns { connected: false }

  • User says "connect my FreshBooks account" or "sign in to FreshBooks"

  • Re-authenticating after a revoked or expired session

TAKES NO ARGUMENTS.

RETURNS: { url: "https://auth.freshbooks.com/oauth/authorize?...", state: "" }

WORKFLOW:

  1. Call auth_get_url → share the url with the user

  2. User visits the URL, authorizes, and is redirected — the redirect URL contains code and state query params

  3. User pastes the code and state back → call auth_exchange_code with both values

Inputs: no named parameters.

auth_revokeA

Revoke the current FreshBooks OAuth session and delete all stored tokens.

WHEN TO USE:

  • User says "disconnect FreshBooks", "sign out", or "remove my FreshBooks connection"

  • Switching to a different FreshBooks account — revoke first, then use auth_get_url for the new account

  • Security: clear stored credentials from this machine

TAKES NO ARGUMENTS.

RETURNS: { success: true, message: "Authentication revoked successfully" }

NOTE: After calling this tool, all accounting and time-tracking tools will return auth errors until a new OAuth session is established via auth_get_url → auth_exchange_code.

Inputs: no named parameters.

auth_statusA

Check whether FreshBooks is connected and return the active session details.

WHEN TO USE:

  • Call first in any workflow before using accounting or time-tracking tools

  • User asks "am I connected to FreshBooks?", "what account is linked?"

  • Diagnose why a tool returned an auth error

TAKES NO ARGUMENTS — safe to call anytime.

RETURNS (connected session): { connected: true, userId, accountId, businessId, email, expiresAt }

  • accountId and businessId are the IDs to pass to accounting and time-tracking tools

RETURNS (no session or expired token): { connected: false }

NEXT STEPS:

  • If connected: false → call auth_get_url to start OAuth

  • If connected: true → use accountId/businessId with all other tools

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool maps to a distinct OAuth lifecycle step: checking status, generating an authorization URL, exchanging the callback code, and revoking the session. There is no meaningful overlap between the tools.

    Naming Consistency4/5

    All tools share the auth_ prefix and use snake_case, which creates a clear family. The minor inconsistency is that auth_status is noun-like while auth_get_url, auth_exchange_code, and auth_revoke are action-oriented.

    Tool Count5/5

    Four tools is well-scoped for the authentication functionality being exposed. Each tool is necessary for completing or managing the FreshBooks OAuth connection, and none are redundant.

    Completeness2/5

    The auth lifecycle itself is complete, but the descriptions repeatedly mention accounting and time-tracking tools that do not exist in this server. After connecting, an agent has no actual FreshBooks accounting operations to call, leaving a significant dead end.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Automates FreshBooks invoicing and time tracking through Claude, allowing users to send invoices, list invoices, log billable hours, and get financial insights via natural language commands.
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      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.
      25
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Integrates with the sevdesk German accounting API, providing 76 tools for full CRUD operations across contacts, invoices, vouchers, orders, credit notes, bank accounts, transactions, parts, tags, addresses, and communication ways.
      6
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides 54 tools across 10 categories for Wave Accounting, enabling invoicing, customer management, products, transactions, bills, estimates, taxes, businesses, and financial reporting through Wave's GraphQL API.
      16 npm
      1
      ISC