CHEVS Garage — FreshBooks MCP + Call Processor

Two systems in one repo:

1. FreshBooks MCP server — 29 tools that let Claude query and update FreshBooks directly (invoices, clients, estimates, expenses, payments, timesheets, reports).

2. Call Processor — records customer phone calls, transcribes them locally with Whisper, extracts job details with Claude, and automatically creates FreshBooks clients/estimates + schedules follow-up reminders.

Cost: $0/month beyond your existing Claude Code subscription.

Quick Start

Full setup from a new machine: follow SETUP.md.

FreshBooks MCP only (no call processor): follow GETTING_STARTED.md.

git clone https://github.com/zeal-tristian-chevier/containerized-freshbooks-mcp.git
cd containerized-freshbooks-mcp

Related MCP server: QuickFile MCP Server

Call Processor — How It Works

Phone call ends
      ↓
Cube ACR auto-uploads audio to Google Drive (Android)
or iOS 18 one-tap share to Google Drive (iPhone)
      ↓
Google Drive for Desktop syncs to watch_folder/ on your PC/Mac
      ↓
Docker container detects the new file (runs 24/7)
      ↓
Whisper transcribes audio locally — free, no internet needed
      ↓
Claude extracts: customer, ATV, work needed, parts, follow-ups
      ↓
FreshBooks: client created/updated + estimate created
      ↓
Email summary sent + follow-up reminders queued

FreshBooks MCP — Tools (29 total)

Time tracking

• check_timesheet — report logged/missing/under-logged days for a day, week, or month

• log_time — log hours per weekday against a project, with PTO exclusion and dry-run

Clients & estimates

• list_clients · create_client

• list_estimates · create_estimate

Invoices & payments

• list_invoices · get_invoice · create_invoice · update_invoice · send_invoice · void_invoice

• list_payments · apply_payment · delete_payment

Expenses

• list_expenses · create_expense · list_expense_categories

Items, taxes & services

• list_items · create_item

• list_taxes · create_tax

• list_services · list_staff

Projects & reports

• list_projects · list_recurring_invoices

• get_profit_loss · get_income_summary · get_accounts_aging

Architecture

Configuration

All settings in .env (copy from .env.example).

FreshBooks OAuth — credentials from my.freshbooks.com → Developer → your app:

Call Processor:

Docker

Two containers, two Dockerfiles:

Start the call processor:

# Windows
.\docker-start.ps1

# macOS
bash docker-start.sh

Register the MCP server with Claude Code (.mcp.json):

{
  "mcpServers": {
    "freshbooks": {
      "command": "docker",
      "args": ["compose", "-f", "/ABS/PATH/TO/docker-compose.yml", "run", "--rm", "-T", "app"]
    }
  }
}

API Notes

Verified live against the FreshBooks v3 API:

• Two hosts. Auth on https://auth.freshbooks.com/oauth/authorize; all data calls on https://api.freshbooks.com.

• Rotating refresh tokens. Each refresh invalidates the old token. The new token is persisted before use, under a lock.

• Time entries use businessId (not accountId). duration is in seconds; started_at is UTC with milliseconds + Z.

• Date filters on payments/expenses are silently ignored by the API — filtering is done client-side after fetching.

• Expense category names are always null in the v3 API for system categories.

• Accounts aging report returns 404 on some account types — falls back to computing aging from outstanding invoice data.

Security

• Token storage — OS keychain by default; encrypted-file fallback uses Fernet with the key in env (never co-located with the ciphertext), 0600 permissions, and atomic writes.

• No secret leakage — TokenSet masks values in repr; token payloads are never logged.

• Safe writes — log_time requires an explicit project_id, defaults to skip_existing=true, supports dry_run, never logs weekends.

• Compromise recovery — revoke in the FreshBooks Developer Portal, then re-run freshbooks-mcp-auth.

Development

pytest            # unit tests

# or in Docker:
docker build --target test -t freshbooks-mcp:test . && docker run --rm freshbooks-mcp:test

License

Internal / private. Not licensed for distribution.