使用说明
freeagent mcp服务器
MCP服务器 自由代理人 会计API。提供76种工具，涵盖发票、费用、联系人、项目、时间表、银行、账单、估算、信用票据、会计报告等。
特性
- OAuth2身份验证 -内置基于浏览器的身份验证流，具有自动令牌刷新功能
- 公司 -公司信息、业务类别、税务时间表
- 用户 -列出、获取、创建、更新和删除用户
- 联系人 -为客户和供应商提供完整的CRUD
- 项目 -创建和管理项目
- 任务 -使用计费率管理项目任务
- 时间表 -使用启动/停止计时器支持跟踪时间
- 发票 -创建、发送和管理带有状态转换的发票
- 估计 -报价、估算和提案以及审批工作流程
- 账单 -管理供应商账单
- 贷记通知 -发放和管理信用票据
- 开支 -跟踪和分类支出
- 银行业 -银行账户和交易管理
- 分类 -浏览会计类别
- 会计报告 -损益表、资产负债表、试算表
先决条件
- 注册一个 FreeAgent开发人员 账户
- 在开发人员仪表板中注册应用程序
- 设置 OAuth重定向类型 到
http://localhost:3456/callback - 注意你的 客户端ID 和 客户端密钥
请参阅 FreeAgent API快速入门 详细说明。
入门指南
1.设置环境变量
export FREEAGENT_CLIENT_ID="your_client_id"
export FREEAGENT_CLIENT_SECRET="your_client_secret"
# export FREEAGENT_SANDBOX=true # uncomment to use sandbox instead of production
2.身份验证（一次性）
npx freeagent-mcp-server auth
这将打开您的浏览器以授权该应用程序。身份验证流支持两种模式：
- 自动 （默认）-端口3456上的本地服务器自动捕获OAuth重定向。当端口可用并且配置了重定向URI时，这是无缝的。
- 手动粘贴回退 -如果重定向不起作用（端口繁忙、防火墙等），只需从浏览器的地址栏复制完整的URL并将其粘贴到终端即可。URL看起来像
http://localhost:3456/callback?code=...&state=....
批准后，令牌将保存到 ~/.freeagent-mcp/tokens.json 并在过期时自动刷新。
3.配置您的MCP客户端
请参阅 配置 下面的部分。
安装
要求： Node.js 18或更高版本。
使用npx（推荐）
npx freeagent-mcp-server
全局安装
npm install -g freeagent-mcp-server
freeagent-mcp
要固定特定版本，请附加 @<version> （例如。 npm install -g freeagent-mcp-server@1.3.0).
从源代码构建
git clone https://github.com/samaxbytez/freeagent-mcp.git
cd freeagent-mcp
npm install
npm run build
npm start
配置
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
FREEAGENT_CLIENT_ID |
是* | 来自开发人员仪表板的OAuth2客户端ID |
FREEAGENT_CLIENT_SECRET |
是* | 来自开发人员仪表板的OAuth2客户端机密 |
FREEAGENT_SANDBOX |
否 | 设置为 true 用于沙盒（默认为生产环境） |
FREEAGENT_ACCESS_TOKEN |
否 | 遗留：直接访问令牌（跳过存储的令牌流） |
FREEAGENT_BASE_URL |
否 | 覆盖API基础URL |
*如果使用，则不需要 FREEAGENT_ACCESS_TOKEN 直接。
克劳德桌面/协作
添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"freeagent": {
"command": "npx",
"args": ["-y", "freeagent-mcp-server"],
"env": {
"FREEAGENT_CLIENT_ID": "your_client_id",
"FREEAGENT_CLIENT_SECRET": "your_client_secret"
}
}
}
}
这适用于Claude Desktop聊天和Claude Cowork。请确保运行 npx freeagent-mcp-server auth 首先在您的终端中完成一次性OAuth设置。
克劳德代码
添加到您的 .mcp.json:
{
"mcpServers": {
"freeagent": {
"command": "npx",
"args": ["-y", "freeagent-mcp-server"],
"env": {
"FREEAGENT_CLIENT_ID": "your_client_id",
"FREEAGENT_CLIENT_SECRET": "your_client_secret"
}
}
}
}
建筑
freeagent-mcp/
├── src/
│ ├── index.ts # Entry point, server setup
│ ├── auth.ts # OAuth2 flow, token storage & refresh
│ ├── client.ts # FreeAgent API HTTP client
│ ├── utils.ts # Shared utilities (responses, logging)
│ ├── auth.test.ts # Auth module tests
│ ├── client.test.ts # Client tests
│ ├── utils.test.ts # Utils tests
│ └── tools/
│ ├── company.ts # Company info tools (3)
│ ├── users.ts # User management tools (6)
│ ├── contacts.ts # Contact CRUD tools (5)
│ ├── projects.ts # Project management tools (5)
│ ├── tasks.ts # Task management tools (5)
│ ├── timeslips.ts # Time tracking tools (7)
│ ├── invoices.ts # Invoice tools (9)
│ ├── estimates.ts # Estimate tools (7)
│ ├── bills.ts # Bill management tools (5)
│ ├── credit-notes.ts # Credit note tools (5)
│ ├── expenses.ts # Expense tracking tools (5)
│ ├── banking.ts # Banking tools (7)
│ ├── categories.ts # Category tools (2)
│ ├── accounting.ts # Accounting report tools (5)
│ └── tools.test.ts # Tool handler tests
├── package.json
├── tsconfig.json
└── smithery.yaml
工具参考
公司（3个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_get_company |
获取公司信息 | GET /company |
freeagent_list_business_categories |
列出业务类别 | GET /company/business_categories |
freeagent_get_tax_timeline |
获取税务时间表 | GET /company/tax_timeline |
用户（6工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_users |
列出具有可选视图筛选器的用户 | GET /users |
freeagent_get_user |
获取特定用户 | GET /users/:id |
freeagent_get_current_user |
获取经过身份验证的用户 | GET /users/me |
freeagent_create_user |
创建新用户 | POST /users |
freeagent_update_user |
更新用户 | PUT /users/:id |
freeagent_delete_user |
删除用户 | DELETE /users/:id |
联系人（5个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_contacts |
通过筛选和排序列出联系人 | GET /contacts |
freeagent_get_contact |
获取特定联系人 | GET /contacts/:id |
freeagent_create_contact |
创建新联系人 | POST /contacts |
freeagent_update_contact |
更新联系人 | PUT /contacts/:id |
freeagent_delete_contact |
删除联系人 | DELETE /contacts/:id |
项目（5个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_projects |
列出具有可选视图筛选器的项目 | GET /projects |
freeagent_get_project |
获取特定项目 | GET /projects/:id |
freeagent_create_project |
创建新项目 | POST /projects |
freeagent_update_project |
更新项目 | PUT /projects/:id |
freeagent_delete_project |
删除项目 | DELETE /projects/:id |
任务（5个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_tasks |
列出具有可选筛选功能的任务 | GET /tasks |
freeagent_get_task |
获取特定任务 | GET /tasks/:id |
freeagent_create_task |
为项目创建新任务 | POST /tasks |
freeagent_update_task |
更新任务 | PUT /tasks/:id |
freeagent_delete_task |
删除任务 | DELETE /tasks/:id |
时间表（7个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_timeslips |
列出带有日期和状态过滤器的时间表 | GET /timeslips |
freeagent_get_timeslip |
获取特定的时间表 | GET /timeslips/:id |
freeagent_create_timeslip |
创建新的时间表 | POST /timeslips |
freeagent_update_timeslip |
更新时间表 | PUT /timeslips/:id |
freeagent_delete_timeslip |
删除时间戳 | DELETE /timeslips/:id |
freeagent_start_timer |
在时间表上启动计时器 | POST /timeslips/:id/timer |
freeagent_stop_timer |
在时间轴上停止计时器 | DELETE /timeslips/:id/timer |
发票（9个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_invoices |
列出带有视图和联系人筛选器的发票 | GET /invoices |
freeagent_get_invoice |
获取特定发票 | GET /invoices/:id |
freeagent_create_invoice |
创建新发票 | POST /invoices |
freeagent_update_invoice |
更新发票 | PUT /invoices/:id |
freeagent_delete_invoice |
删除发票 | DELETE /invoices/:id |
freeagent_mark_invoice_as_sent |
将发票标记为已发送 | PUT /invoices/:id/transitions/mark_as_sent |
freeagent_mark_invoice_as_draft |
将发票标记为草稿 | PUT /invoices/:id/transitions/mark_as_draft |
freeagent_mark_invoice_as_cancelled |
取消发票 | PUT /invoices/:id/transitions/mark_as_cancelled |
freeagent_send_invoice_email |
通过电子邮件发送发票 | POST /invoices/:id/send_email |
估算（7种工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_estimates |
使用过滤器列出估计值 | GET /estimates |
freeagent_get_estimate |
得到一个具体的估计 | GET /estimates/:id |
freeagent_create_estimate |
创建新的估算 | POST /estimates |
freeagent_update_estimate |
更新估算 | PUT /estimates/:id |
freeagent_delete_estimate |
删除估算 | DELETE /estimates/:id |
freeagent_mark_estimate_as_sent |
将估算标记为已发送 | PUT /estimates/:id/transitions/mark_as_sent |
freeagent_mark_estimate_as_approved |
将估算标记为已批准 | PUT /estimates/:id/transitions/mark_as_approved |
账单（5个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_bills |
列出带有视图和日期过滤器的账单 | GET /bills |
freeagent_get_bill |
获取特定账单 | GET /bills/:id |
freeagent_create_bill |
创建新账单 | POST /bills |
freeagent_update_bill |
更新账单 | PUT /bills/:id |
freeagent_delete_bill |
删除账单 | DELETE /bills/:id |
信用票据（5种工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_credit_notes |
列出带有过滤器的贷方票据 | GET /credit_notes |
freeagent_get_credit_note |
获取特定的贷记单 | GET /credit_notes/:id |
freeagent_create_credit_note |
创建新的贷记单 | POST /credit_notes |
freeagent_update_credit_note |
更新贷记单 | PUT /credit_notes/:id |
freeagent_delete_credit_note |
删除贷记单 | DELETE /credit_notes/:id |
费用（5个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_expenses |
列出带有日期和项目筛选器的费用 | GET /expenses |
freeagent_get_expense |
获得特定费用 | GET /expenses/:id |
freeagent_create_expense |
创建新支出 | POST /expenses |
freeagent_update_expense |
更新费用 | PUT /expenses/:id |
freeagent_delete_expense |
删除费用 | DELETE /expenses/:id |
银行业务（7种工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_bank_accounts |
列出银行账户 | GET /bank_accounts |
freeagent_get_bank_account |
获取一个特定的银行账户 | GET /bank_accounts/:id |
freeagent_create_bank_account |
创建新的银行账户 | POST /bank_accounts |
freeagent_update_bank_account |
更新银行账户 | PUT /bank_accounts/:id |
freeagent_delete_bank_account |
删除银行账户 | DELETE /bank_accounts/:id |
freeagent_list_bank_transactions |
列出银行账户的交易记录 | GET /bank_transactions |
freeagent_get_bank_transaction |
获取特定的银行交易 | GET /bank_transactions/:id |
类别（2个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_list_categories |
列出所有会计类别 | GET /categories |
freeagent_get_category |
按标称代码获取特定类别 | GET /categories/:nominal_code |
会计报告（5个工具）
| 工具 | 描述 | API端点 |
|---|---|---|
freeagent_get_profit_and_loss |
获取损益汇总 | GET /accounting/profit_and_loss/summary |
freeagent_get_balance_sheet |
获取资产负债表 | GET /accounting/balance_sheet |
freeagent_get_opening_balances |
获取期初余额 | GET /accounting/balance_sheet/opening_balances |
freeagent_get_trial_balance |
获取试算表摘要 | GET /accounting/trial_balance/summary |
freeagent_get_trial_balance_opening |
获取试算表期初余额 | GET /accounting/trial_balance/summary/opening_balances |
示例提示
- “显示FreeAgent提供的公司信息”
- “列出所有活动联系人”
- “为今天的联系人12345创建一张新发票，付款期限为30天”
- “我这周记录了多少时间？”
- “在时间唇67890上启动计时器”
- “显示我本年度的损益”
- “列出所有逾期发票”
- “在娱乐类别下创建25美元的午餐费用”
- “我目前的资产负债表是什么？”
- “列出供应商的所有未结账单”
发展
# Install dependencies
npm install
# Type check
npm run type-check
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Build
npm run build
# Lint
npm run lint
# Format
npm run format
添加新工具
- 在中创建新文件
src/tools/（或添加到现有的） - 遵循以下模式：导出a
registerXxxTools(server, client)功能 - 将每个工具注册到
server.tool()或server.registerTool() - 总是使用
logToolCall(),jsonResponse()，以及errorResponse() - 在中导入并调用register函数
src/index.ts - 在中添加测试
src/tools/tools.test.ts
故障排除
启动时出现“缺少凭据”错误
集 FREEAGENT_CLIENT_ID 和 FREEAGENT_CLIENT_SECRET 环境变量，然后运行 npx freeagent-mcp-server auth 以进行身份验证。
“未找到存储的令牌”
您需要先完成一次性身份验证流程： npx freeagent-mcp-server auth
身份验证超时
如果自动重定向不起作用，请在批准后从浏览器的地址栏复制完整的URL并将其粘贴到终端中。确保您的FreeAgent应用程序的重定向URI设置为 http://localhost:3456/callback.
端口3456繁忙 身份验证流程将自动回退到手动粘贴模式。批准后，只需从浏览器粘贴重定向URL即可。
401未经授权的错误
您的代币可能已被撤销。重新运行 npx freeagent-mcp-server auth 重新验证。
“FreeAgent API错误（403）” 您的令牌可能没有所需的权限级别。检查您的FreeAgent应用程序是否具有适当的访问范围。
沙盒vs生产
默认情况下，服务器连接到FreeAgent生产API。集 FREEAGENT_SANDBOX=true 使用沙盒。
未找到工具
确保使用正确的工具名称 freeagent_ 前缀（例如。， freeagent_list_invoices，不 list_invoices).
空响应 对于成功的DELETE操作，某些端点返回空响应。这是预期的行为。
释放
从以下位置自动发布 约定式提交 —
看见 发布.md简而言之：合并 feat:/fix: PR至 main
打开发布PR（版本更新+变更日志）；将PR发布合并到npm。
更新日志
看 更改日志.md 关于发布历史。最新发布 版本由此README顶部的npm徽章显示。
许可证
麻省理工学院