CHEVS Garage — FreshBooks MCP + Call Processor

Two systems in one repo:

FreshBooks MCP server — 29 tools that let Claude query and update FreshBooks directly (invoices, clients, estimates, expenses, payments, timesheets, reports).
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

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

Module	Responsibility
`freshbooks_mcp/server.py`	MCP interface — 29 tool definitions + testable `handle_*` functions
`freshbooks_mcp/freshbooks_client.py`	HTTP wrapper: auth injection, 401→refresh→retry, pagination
`freshbooks_mcp/auth_manager.py`	OAuth2 lifecycle: refresh, token rotation, bootstrap CLI
`freshbooks_mcp/token_store.py`	Pluggable storage: OS keychain or Fernet-encrypted file
`freshbooks_mcp/transformers.py`	Pure date math, unit conversion, report building
`call_processor/pipeline.py`	Orchestrates transcribe → extract → FreshBooks → notify
`call_processor/transcriber.py`	Local Whisper transcription (faster-whisper, CPU)
`call_processor/extractor.py`	Runs `claude -p` to extract structured job data
`call_processor/actions.py`	FreshBooks client/estimate creation
`call_processor/scheduler.py`	APScheduler + SQLite reminder queue
`call_processor/watcher.py`	watchdog folder monitor

Configuration

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

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

Variable	Required	Notes
`FRESHBOOKS_CLIENT_ID`	✅	OAuth app client id
`FRESHBOOKS_CLIENT_SECRET`	✅	OAuth app secret
`FRESHBOOKS_REDIRECT_URI`	✅	Must exactly match the app setting (e.g. `https://localhost/callback`)
`FRESHBOOKS_TOKEN_BACKEND`	—	`keyring` (default) or `file`
`FRESHBOOKS_TOKEN_PATH`	—	Encrypted token file path (file backend)
`FRESHBOOKS_TOKEN_KEY`	—	Fernet key for file backend
`TZ`	—	Timezone for day boundaries (default `America/Toronto`)
`DEFAULT_DAILY_HOURS`	—	Expected hours/day (default `8`)

Call Processor:

Variable	Notes
`WHISPER_MODEL`	`tiny` / `base` (default) / `small` / `medium`
`NOTIFY_EMAIL`	Your email — receives a summary after each call
`EMPLOYEE_EMAIL`	Employee email for task reminders
`SMTP_USER` / `SMTP_PASS`	Gmail credentials (use an App Password)

Docker

Two containers, two Dockerfiles:

File	What it builds
`Dockerfile`	MCP server — used by Claude Code/Desktop to query FreshBooks
`Dockerfile.processor`	Call processor — runs 24/7, watches for new audio files

Start the call processor:

# Windows
.\docker-start.ps1

# macOS
bash docker-start.sh

{
  "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.

FreshBooks MCP Server