MCP FreshBooks

mcp-freshbooks

FreshBooks 向けの本番環境対応 MCP サーバーです。請求書、クライアント、経費、支払い、時間追跡、プロジェクト、見積もり、財務レポート、スマートワークフロー用の 53 個のツールを備えています。

特長

• FreshBooks の会計ワークフロー全体をカバーする 53 個のツール
• スマートワークフローツール — 見積もりから請求書への変換、未請求の作業時間の請求、支払い期限を過ぎたクライアントの検索、クライアントの概要の取得
• 5 種類の財務レポート — 損益計算書、税務概要、売掛金年齢表、貸借対照表、回収済み支払い
• トークンの自動更新に対応した OAuth2 認証
• 見やすい出力 — 要約付きリスト、整形された詳細情報
• 本番環境対応のエラー処理とレート制限への対応
• 無料 — FreshBooks の無料開発者プログラムを使用

ツール

カテゴリ	ツール	数
認証	freshbooks_authenticate, freshbooks_authenticate_with_code, freshbooks_whoami	3
請求書	list_invoices, get_invoice, create_invoice, update_invoice, send_invoice, delete_invoice	6
定期請求	list_recurring_invoices, create_recurring_invoice, update_recurring_invoice	3
クライアント	list_clients, get_client, create_client, update_client, delete_client	5
見積もり	list_estimates, get_estimate, create_estimate, update_estimate, send_estimate	5
経費	list_expenses, get_expense, create_expense, update_expense, delete_expense	5
支払い	list_payments, get_payment, create_payment	3
時間追跡	list_time_entries, get_time_entry, create_time_entry, update_time_entry, delete_time_entry	5
プロジェクト	list_projects, get_project, create_project, update_project	4
レポート	get_profit_loss, get_tax_summary, get_accounts_aging, get_balance_sheet, get_payments_collected	5
品目	list_items, create_item	2
カテゴリ	list_expense_categories	1
税金	list_taxes	1
ワークフロー	convert_estimate_to_invoice, get_overdue_invoices, get_unbilled_time, invoice_from_time, client_summary	5

クイックスタート

1. インストール

pip install mcp-freshbooks

または、ソースからインストールします。

git clone https://github.com/AlexlaGuardia/mcp-freshbooks.git
cd mcp-freshbooks
pip install .

2. FreshBooks API の認証情報を取得する

1. freshbooks.com/pages/developer-signup で登録します
2. 開発者ポータルで OAuth アプリを作成します
3. リダイレクト URI に https://localhost:8555/callback を設定します
4. クライアント ID とクライアントシークレットをコピーします

3. 設定する

export FRESHBOOKS_CLIENT_ID=your_client_id
export FRESHBOOKS_CLIENT_SECRET=your_client_secret
export FRESHBOOKS_REDIRECT_URI=https://localhost:8555/callback

4. Claude Desktop に追加する

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "freshbooks": {
      "command": "mcp-freshbooks",
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your_client_id",
        "FRESHBOOKS_CLIENT_SECRET": "your_client_secret",
        "FRESHBOOKS_REDIRECT_URI": "https://localhost:8555/callback"
      }
    }
  }
}

5. 認証する

初回使用時に freshbooks_authenticate ツールを使用します。ブラウザーで開く URL が表示されます。認証後、トークンは ~/.mcp-freshbooks/tokens.json に保存され、自動更新されます。

使用例

未払いのクライアントを確認する

Use get_overdue_invoices to see all past-due clients and total outstanding

提案を請求書に変換する

Use convert_estimate_to_invoice to turn estimate 456 into a ready-to-send invoice

未請求の作業を見つける

Use get_unbilled_time to find time entries not yet on any invoice

収益性を確認する

Get the profit and loss report for Q1 2026

作業時間を記録する

Create a 2-hour time entry for project 789 with note "API integration work"

アーキテクチャ

src/mcp_freshbooks/
├── server.py   # MCP server with 47 tool definitions
├── client.py   # FreshBooks API client (httpx async)
└── auth.py     # OAuth2 flow + token persistence

このサーバーは、すっきりとしたツール登録を実現する FastMCP と MCP Python SDK を使用しています。すべての API 呼び出しは、トークンを自動更新する非同期クライアント経由で行われます。

必要条件

• Python 3.10+
• FreshBooks アカウント（開発には無料トライアルも利用できます）
• FreshBooks OAuth アプリの認証情報

ライセンス

MIT