内容
# @crowdform/freeagent-mcp
适用于 [FreeAgent](https://www.freeagent.com) 会计 API 的 MCP 服务器，以便 Claude 可以处理您的账户：浏览发票、账单、支出、联系人和银行交易，并帮助您 **核对** 未解释的银行活动。
构建针对 [FreeAgent API v2 文档](https://dev.freeagent.com/docs/introduction)（无 OpenAPI 规范 — API 接口由 `docs/api/` 下的手动索引）。
## 设置
零配置 — 默认 OAuth 应用凭证已内置于包中，因此安装并连接：
```sh
claude mcp add freeagent -- npx -y @crowdform/freeagent-mcp
```
或对于 Claude Desktop，添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"freeagent": { "command": "npx", "args": ["-y", "@crowdform/freeagent-mcp"] }
}
}
```
然后要求 Claude **连接到 FreeAgent** — 它运行 `connect_freeagent` 工具，该工具会打开您的浏览器到 FreeAgent 的批准页面。内置凭证仅标识请求的应用程序；除非您在 FreeAgent 自己的登录页面上单击“批准”，否则任何人无法访问您的账户。
## 身份验证和令牌文件的工作原理
您的登录信息存储在 **`~/.freeagent-tokens.json`** 中（使用 `FREEAGENT_TOKEN_PATH` 移动）。当您批准访问时，OAuth 令牌 **和所属组织** （公司名称、子域名、货币）将保存到那里。服务器在每次启动时都会读取该文件，并宣布其登录到的组织，`check_auth_status` 也会报告 — 因此 Claude 始终知道它正在处理哪个账户的账簿。要切换到不同的 FreeAgent 账户，请运行 `connect_freeagent` 并设置 `force=true`（或删除令牌文件），然后批准为其他账户。
令牌会自动刷新；您只需要授权一次（或在刷新令牌被撤销时再次授权）。
### 使用您自己的 OAuth 应用（可选）
除非您覆盖它们，否则使用内置的默认值：在 [dev.freeagent.com](https://dev.freeagent.com) 创建一个应用（我的应用），将其 **OAuth 重定向 URI** 添加到 `http://localhost:8462/callback`，并在环境中设置 `FREEAGENT_CLIENT_ID` / `FREEAGENT_CLIENT_SECRET`（或在运行 `package.json` 时在 `.env` 中）。
设置 `FREEAGENT_SANDBOX=true` 以指向沙盒 — 这需要您自己的沙盒应用；内置应用仅限生产环境使用。
### 从终端授权
从此仓库的 checkout 中，`npm run auth` 运行相同的浏览器流程，无需 MCP 会话，并将令牌保存到相同的位置。
### 无本地主机回调授权
如果您无法（或不愿意）注册本地主机重定向 URI，请通过其他方式获取刷新令牌 — 例如 [Google OAuth 游戏场](https://developers.google.com/oauthplayground)（齿轮图标 → “使用您自己的 OAuth 凭证”，授权端点 `https://api.freeagent.com/v2/approve_app`，令牌端点 `https://api.freeagent.com/v2/token_endpoint`）— 然后导入：
```sh
npm run auth -- --refresh-token <refresh_token>
```
这会将刷新令牌兑换为访问令牌，验证它与 API，然后将两者保存到令牌文件中。FreeAgent 刷新令牌是长期有效的（直到您撤销应用程序的访问权限），服务器会自动在每次刷新时旋转/持久化它们 — 因此这是一个一次性步骤。
## 它可以做什么
- **公司和参考数据** — 公司信息、用户、类别（带有名义代码）、联系人
- **销售** — 列出/获取/创建发票、状态转换、信用通知、估算
- **采购** — 账单和支出
- **银行** — 银行账户、银行交易（筛选未解释/手动/等）
- **核对** — 创建/更新/删除银行交易说明（链接到发票、账单、转账或分类的收支），以及一个匹配助手，根据金额、日期和参考，配对未解释的交易与开放发票/账单
- **报告** — 利润和亏损、资产负债表、试算平衡表、增值税申报表、总账交易
## 注意事项
- FreeAgent 通过 **URL** 标识资源（例如 `https://api.freeagent.com/v2/invoices/123`）。工具接受完整的 URL 或裸露的数字 ID。
- 列表工具最多获取 4 页的 100 个项目，并在结果被截断时通知您。
- 速率限制（120/分钟）通过 429 自动退避处理。
- 连接的组织（名称、子域名、货币）在授权时与令牌一起保存，在服务器启动时在 MCP 说明中宣布，并由 `check_auth_status` 返回 — 因此助手始终知道它正在处理哪个账户的账簿。
## 许可证和免责声明
MIT — 见 [LICENSE](LICENSE)。这是非官方集成，不受 FreeAgent Central Ltd 的赞助或认可。“FreeAgent”是 FreeAgent Central Ltd 的商标；通过此软件访问 FreeAgent API 和任何数据的所有权归 FreeAgent 和各自的账户持有者所有。您使用此软件访问 API 需遵守 FreeAgent 自己的条款。
