FreshBooks MCP Server

FreshBooks MCP服务器

模型上下文协议（MCP）服务器，为Claude和其他MCP兼容的AI助手提供完整的FreshBooks集成。

特性

• 完整的SDK奇偶校验 -87个工具，涵盖所有主要的FreshBooks功能
• 22实体类别 -全面涵盖会计、发票、时间跟踪等
• 时间追踪 -记录时间、管理计时器、跟踪计费小时数
• 发票和账单 -创建发票、管理账单、处理付款
• 费用管理 -跟踪支出、分类支出、管理供应商
• 客户与项目管理 -全面的CRM和项目能力
• 财务报告 -损益、税务摘要等
• OAuth2身份验证 -基于令牌的安全身份验证，具有自动刷新功能

安装

npm install @goodsamsoftware/freshbooks-mcp

快速开始

最快的开始方式是我们的 托管式服务 --不需要OAuth设置。

1.注册

首选 freshbooks.goodsamsoftware.com 并创建一个帐户(14天免费试用).登录后，从仪表板连接您的FreshBooks帐户。

2.复制您的配置

从仪表板中复制提供的配置片段。它对两者都有效 克劳德桌面 和 克劳德代码.

克劳德桌面 (claude_desktop_config.json):

{
  "mcpServers": {
    "freshbooks": {
      "command": "npx",
      "args": ["mcp-remote", "https://freshbooks.goodsamsoftware.com/api/mcp", "--header", "Authorization:Bearer YOUR_TOKEN"]
    }
  }
}

克劳德代码 (.mcp.json 在您的项目中）：

{
  "mcpServers": {
    "freshbooks": {
      "command": "npx",
      "args": ["mcp-remote", "https://freshbooks.goodsamsoftware.com/api/mcp", "--header", "Authorization:Bearer YOUR_TOKEN"]
    }
  }
}

3.开始使用

示例提示：

• “在网站重新设计项目上登录2小时”
• “显示我本周的时间条目”
• “启动客户会议计时器”
• “为Acme Corp开具1500美元的发票”
• “我这个月的利润/亏损是多少？”

______________________________________________________________________

自托管设置

您还可以使用自己的FreshBooks API应用程序在本地运行MCP服务器。

注： FreshBooks要求所有OAuth回调URL（包括localhost）都使用HTTPS。看 本地HTTPS设置 下面是说明。

1.获取FreshBooks证书

1. 首选 FreshBooks开发者门户
2. 创建新应用程序
3. 将重定向URI设置为： https://freshbooks.goodsamsoftware.com/callback
4. 记下您的客户端ID和客户端密码

2.配置克劳德桌面

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "freshbooks": {
      "command": "npx",
      "args": ["@goodsamsoftware/freshbooks-mcp"],
      "env": {
        "FRESHBOOKS_CLIENT_ID": "your-client-id",
        "FRESHBOOKS_CLIENT_SECRET": "your-client-secret",
        "FRESHBOOKS_REDIRECT_URI": "https://freshbooks.goodsamsoftware.com/callback"
      }
    }
  }
}

3.身份验证

问克劳德：

“将我连接到FreshBooks”

Claude将指导您完成OAuth身份验证。在FreshBooks中授权后，您将在我们的 托管回调页面 -只需复制并粘贴回克劳德。

4.开始使用

示例提示：

• “在网站重新设计项目上登录2小时”
• “显示我本周的时间条目”
• “启动客户会议计时器”
• “为Acme Corp开具1500美元的发票”
• “我这个月的利润/亏损是多少？”

可用工具（共87个）

身份验证（5个工具）

时间追踪（5个工具）

定时器管理（4个工具）

发票（5个工具）

客户端（5个工具）

项目（5个工具）

费用（5个工具）

账单和付款（15个工具）

其他工具

*请参阅中的完整工具文档 docs/api/*

配置（自托管）

环境变量

高级：本地HTTPS设置

如果您更喜欢使用本地回调而不是我们的托管回调页面，您可以使用设置本地HTTPS证书 mkcert:

窗户（翼子板）：

winget install FiloSottile.mkcert
mkcert -install
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1

macOS（Homebrew）：

brew install mkcert
mkcert -install
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1

Linux：

# Install mkcert (see https://github.com/FiloSottile/mkcert#installation)
mkcert -install
mkdir certs
mkcert -key-file certs/localhost-key.pem -cert-file certs/localhost.pem localhost 127.0.0.1 ::1

然后将重定向URI设置为 https://localhost:3000/callback 在FreshBooks。

证书有效期为3年，并受您的系统信任。

发展

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Build for production
npm run build

测试

该项目具有全面的测试覆盖范围：

• 1571次测试 93个测试文件
• 100%代码覆盖率 需求
• 所有FreshBooks实体的模拟工厂
• 错误场景覆盖率

npm test                 # Run all tests
npm run test:coverage    # Run with coverage report

建筑

src/
├── server.ts             # MCP server entry point
├── auth/                 # OAuth2 authentication
├── client/               # FreshBooks SDK wrapper
├── errors/               # Error normalization
├── tools/                # MCP tool implementations (22 categories)
│   ├── auth/             # Authentication tools
│   ├── time-entry/       # Time tracking
│   ├── timer/            # Timer management
│   ├── invoice/          # Invoicing
│   ├── client/           # Client management
│   ├── project/          # Projects
│   ├── expense/          # Expenses
│   ├── bill/             # Bills
│   └── ...               # 14 more categories
└── config/               # Configuration

文档

• api参考 -完整的工具文档
• 身份验证设置 -OAuth配置
• 克劳德指南 -Claude优化使用示例
• 例子 -工作流示例

错误处理

所有错误都标准化为MCP格式，并附有有用的上下文：

{
  "code": -32005,
  "message": "User-friendly message",
  "data": {
    "freshbooksError": { "code": "...", "message": "..." },
    "recoverable": true,
    "suggestion": "What to do next"
  }
}

许可证

MIT许可证-请参阅 许可证 了解详情。

学分

• 模型上下文协议
• MCP TypeScript SDK