mcpengine/servers/freshbooks/README.md

# 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

```bash
npm install
npm run build
```

## Configuration

Set environment variables:

```bash
export FRESHBOOKS_ACCOUNT_ID="your_account_id"
export FRESHBOOKS_BEARER_TOKEN="your_bearer_token"
```

## Usage

### As MCP Server

Add to your MCP settings:

```json
{
  "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

```bash
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

```typescript
{
  "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

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

### Track Time

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

### Generate Profit/Loss Report

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

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

## License

MIT

## Author

MCPEngine - Complete MCP implementations for modern platforms