FreshBooks MCP by Good Samaritan Software

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

Quick Start — Hosted Service (Recommended)

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)

Clients (5 tools)

Time Tracking (9 tools)

Projects (5 tools)

Expenses (5 tools)

Payments (5 tools)

Bills (10 tools)

Vendors (5 tools)

Reports (3 tools — all read-only)

Additional Tools

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

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

• Full Documentation

• API Reference - Complete tool documentation

• Authentication Setup - OAuth configuration

• Examples - Workflow examples

License

MIT License — see LICENSE for details.

Credits

• FreshBooks Node.js SDK

• Model Context Protocol

• MCP TypeScript SDK