MCP FreshBooks

mcp-freshbooks

面向 FreshBooks 的生产级 MCP 服务，提供 53 个工具，涵盖发票、客户、费用、付款、时间跟踪、项目、报价、财务报告和智能工作流。

功能

• 53 个工具，涵盖完整的 FreshBooks 会计工作流
• 智能工作流工具——将报价转换为发票、为未开票的工时开具发票、查找逾期客户、获取完整的客户摘要
• 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

该服务使用 MCP Python SDK 和 FastMCP，以简洁地注册工具。所有 API 调用均通过异步客户端发起，并自动刷新令牌。

要求

• Python 3.10+
• FreshBooks 账户（免费试用账户可用于开发）
• FreshBooks OAuth 应用凭据

许可证

MIT