FreshBooks Server

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

---

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

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.