FreshBooks MCP Server

A Model Context Protocol (MCP) server providing complete FreshBooks integration for Claude and other MCP-compatible AI assistants.

Features

• Complete SDK Parity - 87 tools covering all major FreshBooks functionality
• 22 Entity Categories - Full coverage of accounting, invoicing, time tracking, and more
• Time Tracking - Log time, manage timers, track billable hours
• Invoicing & Billing - Create invoices, manage bills, handle payments
• Expense Management - Track expenses, categorize spending, manage vendors
• Client & Project Management - Full CRM and project capabilities
• Financial Reports - Profit/loss, tax summaries, and more
• OAuth2 Authentication - Secure token-based authentication with auto-refresh

Installation

npm install @goodsamsoftware/freshbooks-mcp

Quick Start

The fastest way to get started is with our hosted service — no OAuth setup required.

1. Sign Up

Go to freshbooks.goodsamsoftware.com and create an account (14-day free trial). Once you're in, connect your FreshBooks account from the dashboard.

2. Copy Your Configuration

From your dashboard, copy the configuration snippet provided. It works with both Claude Desktop and Claude Code.

Claude Desktop (claude_desktop_config.json):

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

Claude Code (.mcp.json in your project):

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

3. Start Using

Example prompts:

• "Log 2 hours on the Website Redesign project"
• "Show me my time entries for this week"
• "Start a timer for client meeting"
• "Create an invoice for Acme Corp for $1,500"
• "What's my profit/loss this month?"

Self-Hosted Setup

You can also run the MCP server locally with your own FreshBooks API application.

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

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. Configure Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "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 authentication. After authorizing in FreshBooks, you'll see the authorization code on our hosted callback page - just copy it and paste it back to Claude.

4. Start Using

Example prompts:

• "Log 2 hours on the Website Redesign project"
• "Show me my time entries for this week"
• "Start a timer for client meeting"
• "Create an invoice for Acme Corp for $1,500"
• "What's my profit/loss this month?"

Available Tools (87 total)

Authentication (5 tools)

Time Tracking (5 tools)

Timer Management (4 tools)

Invoicing (5 tools)

Clients (5 tools)

Projects (5 tools)

Expenses (5 tools)

Bills & Payments (15 tools)

Additional Tools

See complete tool documentation in docs/api/

Configuration (Self-Hosted)

Environment Variables

Advanced: Local HTTPS Setup

If you prefer to use a local callback instead of our hosted callback page, you can set up local HTTPS certificates with mkcert:

Windows (winget):

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

macOS (Homebrew):

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

Linux:

# Install mkcert (see https://github.com/FiloSottile/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.

The certificates will be valid for 3 years and trusted by your system.

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Build for production
npm run build

Testing

The project has comprehensive test coverage:

• 1,571 tests across 93 test files
• 100% code coverage requirement
• Mock factories for all FreshBooks entities
• Error scenario coverage

npm test                 # Run all tests
npm run test:coverage    # Run with coverage report

Architecture

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

Documentation

• API Reference - Complete tool documentation
• Authentication Setup - OAuth configuration
• Claude Guide - Claude-optimized usage examples
• Examples - Workflow examples

Error Handling

All errors are normalized to MCP format with helpful context:

{
  "code": -32005,
  "message": "User-friendly message",
  "data": {
    "freshbooksError": { "code": "...", "message": "..." },
    "recoverable": true,
    "suggestion": "What to do next"
  }
}

License

MIT License - see LICENSE for details.

Credits

• FreshBooks Node.js SDK
• Model Context Protocol
• MCP TypeScript SDK