mcpengine/servers/freshbooks

FreshBooks MCP Server

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):

1. invoice-dashboard - Overview of all invoices with stats
2. invoice-detail - Single invoice view
3. invoice-builder - Create/edit invoices
4. invoice-grid - Grid view of invoices
5. client-dashboard - Client overview with metrics
6. client-detail - Single client view
7. client-grid - Grid view of clients
8. expense-dashboard - Expense overview
9. expense-tracker - Add and track expenses
10. estimate-builder - Create/edit estimates
11. estimate-grid - Grid view of estimates
12. time-tracker - Real-time timer for tracking hours
13. time-entries - List of time entries
14. project-dashboard - Project overview with progress
15. project-detail - Single project view
16. payment-history - List of all payments
17. reports-dashboard - Reports menu
18. profit-loss - Profit & loss report
19. tax-summary - Tax summary report
20. aging-report - Accounts aging report
21. recurring-invoices - Recurring invoice profiles
22. 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