AI导哈

会计API服务器

FreeAgent MCP服务器是一个将FreeAgent会计API v2暴露为188个工具的服务，适用于Claude、Cursor和其他MCP兼容客户端。

  • by daaaaan
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 daaaaan/freeagent-mcp

使用说明

FreeAgent MCP服务器

一个MCP（模型上下文协议）服务器，将整个FreeAgent记帐API v2公开为188个工具，用于Claude、Cursor和其他兼容MCP的客户端。

认证

FreeAgent使用OAuth 2.0。您需要完成一次性授权流程以获取令牌，然后服务器会自动处理刷新。

步骤1：创建FreeAgent应用程序

  1. 首选 https://dev.freeagent.com 并登录
  2. 点击 创建新应用程序
  3. 填写：
    • 名字：随你喜欢（例如“MCP服务器”）
    • OAuth重定向类型: http://localhost:3000/callback （你需要这个来兑换代币）
  4. 注意你的 OAuth标识符 （客户端ID）和 OAuth密钥 （客户机密）

对于测试，请使用沙盒 https://dev.freeagent.com沙盒应用程序获得单独的客户端ID/密钥并点击 api.sandbox.freeagent.com 而不是 api.freeagent.com.

步骤2：获取您的授权码

在浏览器中打开此URL（替换占位符）：

https://api.freeagent.com/v2/approve_app?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback

对于 沙盒，使用：

https://api.sandbox.freeagent.com/v2/approve_app?response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=http://localhost:3000/callback

登录并授权应用程序。您将被重定向到您的回调URL ?code=XXXXX 参数。复制该代码，它将在15分钟后过期。

步骤3：将代码兑换成代币

curl -X POST https://api.freeagent.com/v2/token_endpoint \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -u "YOUR_CLIENT_ID:YOUR_CLIENT_SECRET" \
  -d "grant_type=authorization_code&code=YOUR_AUTH_CODE&redirect_uri=http://localhost:3000/callback"

对于 沙盒，替换 api.freeagent.com 随着 api.sandbox.freeagent.com.

你会回来的：

{
  "access_token": "abc123...",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": "def456...",
  "refresh_token_expires_in": 7776000
}

保存 access_token 和 refresh_token.

步骤4：配置MCP服务器

设置这些环境变量：

export FREEAGENT_CLIENT_ID="your_oauth_identifier"
export FREEAGENT_CLIENT_SECRET="your_oauth_secret"
export FREEAGENT_ACCESS_TOKEN="abc123..."
export FREEAGENT_REFRESH_TOKEN="def456..."
export FREEAGENT_SANDBOX="true"   # omit or set to "false" for production

步骤5：添加到MCP客户端

克劳德桌面版 (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["/path/to/freeagent-mcp/dist/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_ACCESS_TOKEN": "your_access_token",
        "FREEAGENT_REFRESH_TOKEN": "your_refresh_token",
        "FREEAGENT_SANDBOX": "true"
      }
    }
  }
}

克劳德代码 (~/.claude/settings.json):

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["/path/to/freeagent-mcp/dist/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_ACCESS_TOKEN": "your_access_token",
        "FREEAGENT_REFRESH_TOKEN": "your_refresh_token",
        "FREEAGENT_SANDBOX": "true"
      }
    }
  }
}

令牌刷新的工作原理

您只需要手动获取一次令牌。之后：

  1. 服务器在每次API调用之前检查令牌过期
  2. 如果访问令牌在5分钟内过期，它将使用您的刷新令牌和客户端凭据自动刷新
  3. 新令牌保存到 ~/.freeagent-mcp/tokens.json （文件权限 0600)
  4. 如果设置了环境变量，则它们优先于保存的令牌文件

最后访问令牌 约1小时.最后刷新令牌 ~90天。如果您的刷新令牌过期（例如服务器在3个多月内未运行），您需要重复步骤2-4。

令牌存储

令牌存储在两个地方（按优先级顺序）：

来源 使用时
环境变量(FREEAGENT_ACCESS_TOKEN, FREEAGENT_REFRESH_TOKEN) 总是先检查。在MCP客户端配置中设置这些。
令牌文件(~/.freeagent-mcp/tokens.json) 后退。每次令牌刷新时自动更新。

令牌文件是通过以下方式创建的 0600 权限（仅限所有者读/写） 0700 目录。

速率限制

FreeAgent对每个用户强制执行这些限制：

限制 阈值
每分钟 120个请求
每小时 3600个请求
令牌刷新 每分钟15次

服务器处理 429 Too Many Requests 自动响应——它读取 Retry-After 标头并等待重试（最多3次尝试）。

沙盒vs生产

沙箱 生产
API基本URL api.sandbox.freeagent.com/v2 api.freeagent.com/v2
验证URL api.sandbox.freeagent.com/v2/approve_app api.freeagent.com/v2/approve_app
环境变量 FREEAGENT_SANDBOX=true FREEAGENT_SANDBOX=false （或省略）
应用程序凭据 将客户端ID/机密与开发门户分开 将客户端ID:机密与开发入口分开
数据 测试数据，可安全实验 真实会计数据

使用沙盒进行开发和测试。沙箱和生产使用 分开 具有不同凭据的OAuth应用程序。

从源头构建

npm install
npm run build

故障排除

“未通过身份验证”错误：您的访问令牌丢失或已过期，并且没有可用的刷新令牌。重新运行OAuth流程（步骤2-4）。

“令牌刷新失败：401”：您的客户端ID/密码错误，或者刷新令牌已过期（>90天）。创建新的授权码并进行交换。

“重试3次后超过速率限制”：你严重违反了FreeAgent的费率限制。分隔您的请求或减少并行工具调用的数量。

“FreeAgent API错误：…”：API返回错误。该消息包括FreeAgent的错误详细信息。检查 FreeAgent API文档 对于特定的端点。

相关 MCP