FreshBooks MCP Server

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

License: MIT TypeScript Tests

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

Go to FreshBooks Developer Portal
Create a new application
Set redirect URI to: https://freshbooks.goodsamsoftware.com/callback
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

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

Go to FreshBooks Developer Portal
Create a new application
Note your Client ID and Client Secret
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.

FreshBooks MCP Server

FreshBooks MCP Server

Features

Installation

Quick Start

1. Get FreshBooks Credentials

2. Configure Claude Desktop

3. Authenticate

4. Start Using

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

Configuration

Environment Variables

Getting FreshBooks Credentials

Advanced: Local HTTPS Setup

Development

Testing

Architecture

Documentation

Error Handling

License

Credits

Resources

New MCP Servers

Latest Blog Posts

MCP directory API