Complete Model Context Protocol server for FreshBooks accounting platform. Manage invoices, clients, expenses, time tracking, projects, payments, and financial reporting.

Features

🎯 55+ Tools

Invoices (10 tools)

List, get, create, update, delete invoices
Send invoices via email
Mark paid/unpaid, create payments
Get payment history

Clients (6 tools)

List, get, create, update, delete clients
List client contacts

Expenses (6 tools)

List, get, create, update, delete expenses
List expense categories

Estimates (7 tools)

List, get, create, update, delete estimates
Send estimates, convert to invoices

Time Tracking (5 tools)

List, get, create, update, delete time entries

Projects (6 tools)

List, get, create, update, delete projects
List project services

Payments (5 tools)

List, get, create, update, delete payments

Items (5 tools)

List, get, create, update, delete items (products/services)

Taxes (5 tools)

List, get, create, update, delete taxes

Reports (5 tools)

Profit & Loss report
Tax summary
Accounts aging
Expense report
Revenue by client

Recurring (5 tools)

List, get, create, update, delete recurring profiles

Accounts (3 tools)

Get account details
List staff members
Get current user

🎨 22 React MCP Apps

Dark-themed, client-side state React apps (inline HTML):

invoice-dashboard - Overview of all invoices with stats
invoice-detail - Single invoice view
invoice-builder - Create/edit invoices
invoice-grid - Grid view of invoices
client-dashboard - Client overview with metrics
client-detail - Single client view
client-grid - Grid view of clients
expense-dashboard - Expense overview
expense-tracker - Add and track expenses
estimate-builder - Create/edit estimates
estimate-grid - Grid view of estimates
time-tracker - Real-time timer for tracking hours
time-entries - List of time entries
project-dashboard - Project overview with progress
project-detail - Single project view
payment-history - List of all payments
reports-dashboard - Reports menu
profit-loss - Profit & loss report
tax-summary - Tax summary report
aging-report - Accounts aging report
recurring-invoices - Recurring invoice profiles
revenue-chart - Revenue visualization

Installation

npm install
npm run build

Configuration

Set environment variables:

export FRESHBOOKS_ACCOUNT_ID="your_account_id"
export FRESHBOOKS_BEARER_TOKEN="your_bearer_token"

Usage

As MCP Server

Add to your MCP settings:

{
  "mcpServers": {
    "freshbooks": {
      "command": "node",
      "args": ["/path/to/freshbooks/dist/main.js"],
      "env": {
        "FRESHBOOKS_ACCOUNT_ID": "your_account_id",
        "FRESHBOOKS_BEARER_TOKEN": "your_bearer_token"
      }
    }
  }
}

Direct Usage

npm start

Architecture

src/
├── clients/
│   └── freshbooks.ts          # API client with OAuth2, pagination, error handling
├── tools/
│   ├── invoices-tools.ts      # 10 invoice tools
│   ├── clients-tools.ts       # 6 client tools
│   ├── expenses-tools.ts      # 6 expense tools
│   ├── estimates-tools.ts     # 7 estimate tools
│   ├── time-entries-tools.ts  # 5 time tracking tools
│   ├── projects-tools.ts      # 6 project tools
│   ├── payments-tools.ts      # 5 payment tools
│   ├── items-tools.ts         # 5 item tools
│   ├── taxes-tools.ts         # 5 tax tools
│   ├── reports-tools.ts       # 5 report tools
│   ├── recurring-tools.ts     # 5 recurring tools
│   └── accounts-tools.ts      # 3 account tools
├── types/
│   └── index.ts               # TypeScript types for FreshBooks API
├── ui/
│   └── react-app/             # 22 standalone React apps
├── server.ts                  # MCP server implementation
└── main.ts                    # Entry point

API Client Features

OAuth2 Bearer Authentication
Automatic Pagination - Fetch all pages or paginated results
Error Handling - Structured error responses
Rate Limiting - Respects FreshBooks API limits
Type Safety - Full TypeScript support

Example Tool Calls

Create Invoice

{
  "name": "freshbooks_create_invoice",
  "arguments": {
    "clientid": 12345,
    "lines": [
      { "name": "Website Design", "qty": 1, "unit_cost": "2500.00" },
      { "name": "Hosting Setup", "qty": 1, "unit_cost": "150.00" }
    ],
    "currency_code": "USD",
    "notes": "Thank you for your business!"
  }
}

List Overdue Invoices

{
  "name": "freshbooks_list_invoices",
  "arguments": {
    "status": "overdue",
    "per_page": 50
  }
}

Track Time

{
  "name": "freshbooks_create_time_entry",
  "arguments": {
    "duration": 7200,
    "note": "Website development",
    "started_at": "2024-01-15T09:00:00Z",
    "projectid": 456
  }
}

Generate Profit/Loss Report

{
  "name": "freshbooks_profit_loss_report",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31",
    "currency_code": "USD"
  }
}

Development

Build

npm run build

Watch Mode

npm run watch

License

MIT

Author

MCPEngine - Complete MCP implementations for modern platforms