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 freshbooks-mcp

Quick Start

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": ["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)

Tool	Description
auth_status	Check authentication status
auth_get_url	Get OAuth authorization URL
auth_exchange_code	Exchange auth code for tokens
auth_refresh	Refresh access token
auth_revoke	Revoke authentication

Time Tracking (5 tools)

Tool	Description
timeentry_list	List time entries with filters
timeentry_single	Get time entry by ID
timeentry_create	Create time entry
timeentry_update	Update time entry
timeentry_delete	Delete time entry

Timer Management (4 tools)

Tool	Description
timer_start	Start a timer
timer_stop	Stop timer and log time
timer_current	Get running timer(s)
timer_discard	Delete timer without logging

Invoicing (5 tools)

Tool	Description
invoice_list	List invoices
invoice_single	Get invoice by ID
invoice_create	Create invoice
invoice_update	Update invoice
invoice_delete	Delete invoice

Clients (5 tools)

Tool	Description
client_list	List clients
client_single	Get client by ID
client_create	Create client
client_update	Update client
client_delete	Delete client

Projects (5 tools)

Tool	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	Description
expense_list	List expenses
expense_single	Get expense by ID
expense_create	Create expense
expense_update	Update expense
expense_delete	Delete expense

Bills & Payments (15 tools)

Tool	Description
bill_list	List bills
bill_single	Get bill by ID
bill_create	Create bill
bill_update	Update bill
bill_delete	Delete bill
billpayment_list	List bill payments
billpayment_single	Get bill payment
billpayment_create	Create bill payment
billpayment_update	Update bill payment
billpayment_delete	Delete bill payment
billvendor_list	List vendors
billvendor_single	Get vendor by ID
billvendor_create	Create vendor
billvendor_update	Update vendor
billvendor_delete	Delete vendor

Additional Tools

Category	Tools	Description
Credit Notes	5	Create, manage credit notes
Expense Categories	3	Manage expense categories
Items	5	Product/service catalog
Journal Entries	5	Manual accounting entries
Journal Entry Accounts	3	Chart of accounts
Other Income	5	Non-invoice income tracking
Payments	5	Invoice payment tracking
Payment Options	2	Payment gateway settings
Reports	3	Financial reports
Services	5	Billable service types
Tasks	5	Project task management
User	1	Current user info
Callbacks	5	Webhook management

See complete tool documentation in docs/api/

Configuration

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)

Getting FreshBooks Credentials

1. Go to FreshBooks Developer Portal
2. Create a new application
3. Note your Client ID and Client Secret
4. Set redirect URI to: https://freshbooks.goodsamsoftware.com/callback

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