Onexur Manager MCP

Onexur Manager MCP

一个 MCP（模型上下文协议）服务，可将 Claude 和 ChatGPT 等 AI 助手连接到 Manager 会计实例。它将 Manager 的数据和操作作为一组受限工具开放。默认情况下为只读，开箱即用地提供报告、诊断和对账工具，并通过显式配置控制所有写入功能。

本项目最初是从 manager-mcp 0.2.6 分叉而来。请参阅下文的致谢。

1. 项目介绍

Onexur Manager MCP 让 AI 助手通过结构化工具接口读取 Manager 会计实例，并在明确许可的情况下对其执行操作，而不是使用自由格式的 API 调用。服务端实施分级权限模型：读取权限和写入权限需要分别启用，删除权限则需要再次单独启用。

典型用途：

• 请助手解释余额、查找未付款发票或汇总账户活动。
• 无需编写脚本即可运行对账和诊断检查（重复交易、未分配付款、无效的发票引用、待查账户候选项）。
• 根据 Manager 的分类账重建过去某一日期的试算平衡表、损益表或账龄余额，并明确标注为重建结果，而非正式报告。
• 针对特定交易类型提出更正方案，并在审核后应用；始终采用明确的先提议、后应用流程，而非直接写入。

默认情况下，不会注册任何会更改 Manager 的功能。每个写入请求在查询任何权限范围之前，也都会经过永久拒绝列表检查（请参阅配置）。

2. 安装

软件包名为 mcp-manager.io，Python 模块名为 manager_mcp，命令为 manager-mcp 和 manager-mcp-dev。需要 Python 3.10 或更高版本以及 uv。

在 PyPI 上发布首个版本之前，请从克隆的仓库运行：

git clone https://github.com/onexurOSS/mcp-manager.io.git
cd mcp-manager.io
uv sync
uv run manager-mcp

发布后，无需克隆：

uvx --from mcp-manager.io manager-mcp

该服务通过 stdio 使用 MCP。要从客户端使用，请将客户端配置为运行上述某条命令，并将 Manager 连接详细信息作为环境变量传入，例如：

{
  "mcpServers": {
    "manager": {
      "command": "uvx",
      "args": ["--from", "mcp-manager.io", "manager-mcp"],
      "env": {
        "MANAGER_API_URL": "http://127.0.0.1:55667/api2",
        "MANAGER_API_KEY": "your-access-token"
      }
    }
  }
}

本仓库中的客户端集成：

• mcpb/ 存放 Claude Desktop 扩展包的清单。不会提交构建后的扩展包。该清单通过 uv 运行已发布的 mcp-manager.io 软件包，因此在软件包发布后即可使用。
• .cursor-plugin/plugin.json 是一个 Cursor 插件清单。
• 对于其他客户端，例如在你自己的项目中配置 .cursor/mcp.json 或 .vscode/mcp.json，请使用上述模式。

ChatGPT Apps 需要托管的 HTTP 端点。本软件包仅支持 stdio。

3. 配置

一个进程与一个 Manager 实例通信，通过环境变量进行配置：

变量	用途
MANAGER_API_URL	Manager API 的基础 URL；必要时包含 /api2。必填。
MANAGER_API_KEY	在 Manager Settings 中创建的访问令牌，通过 X-API-KEY 发送。必填。
MANAGER_MCP_WRITE_SCOPES	以逗号分隔的写入范围。默认为空。
MANAGER_MCP_DELETE_SCOPES	以逗号分隔的删除范围。默认为空，且不会因写入范围而自动启用。
MANAGER_MCP_AUDIT_LOG_PATH	将更正性写入操作记录为 JSON 行（包含操作前后的状态）的位置。默认为 ~/.manager_mcp/audit_log.jsonl。
MANAGER_MCP_DEV_SUPERVISOR	设为 1，在源文件发生更改时自动重启服务。仅用于开发。

旧版变量 MANAGER_MCP_ALLOW_WRITES、ALLOW_WRITES 和 MANAGER_MCP_WRITES 会被拒绝，并显示指向上述两个范围变量的错误。

切勿提交 API 密钥。请将其保存在 MCP 客户端的环境中，或存放在私有环境文件中。

传输方式

stdio 是默认传输方式，也是通过注册表启动的（uvx）进程唯一使用的传输方式。HTTP 是一种额外的可选方式，适用于需要通过网络而非仅通过本地 stdio 管道访问此服务的可自托管部署：

变量	用途
MANAGER_MCP_TRANSPORT	stdio（默认）或 http。
MANAGER_MCP_HTTP_HOST	HTTP 模式的绑定主机。未设置时默认为环回地址（127.0.0.1）。
MANAGER_MCP_HTTP_PORT	HTTP 模式的绑定端口。未设置时默认为 8000。
MANAGER_MCP_HTTP_AUTH_TOKEN	可选的 bearer 令牌。设置后，每个 HTTP 请求都必须携带匹配的 Authorization: Bearer <token> 标头，否则会在到达任何工具之前被拒绝，并返回 401。

HTTP 模式公开的工具完全相同，范围/策略强制规则完全相同，每个进程仅对应一个 Manager 实例的模型也完全相同——变化的只有传输方式。它不会增加多租户支持，也不会允许每个进程运行多个 Manager 实例；这些功能应由部署在本服务前方的独立网关服务提供。

安全提示：MANAGER_MCP_HTTP_AUTH_TOKEN 是整个进程共用的单一密钥，在传输层进行检查——它不是针对每个调用方的身份验证、OAuth，也不能替代真正的身份验证边界。未设置该变量时，HTTP 模式完全没有传输层身份验证：任何能够访问已配置主机:端口的客户端都能调用此进程公开的每个工具，唯一的限制是上述范围/拒绝列表策略（它规定可以执行哪些操作，而非谁可以连接）。只有当网络部署方式——环回绑定、私有 Docker 网络、VPN，或执行真正身份验证的网关/反向代理——确实是唯一访问控制手段时，这样做才安全。如果 HTTP 模式未配置令牌，服务启动时会向 stderr 打印警告，而不会对此保持沉默。鉴于此服务可能会公开真实的簿记数据（并且根据配置的范围，可能允许写入/删除这些数据），强烈建议运维人员设置令牌、将服务部署在网关之后，或同时采取这两种措施。

权限范围

有效范围包括 quotes、orders、parties、items、sales、purchases、banking、payroll 和 ledger，以及一个用于紧急情况下启用所有领域完整创建和更新（或删除）权限的 raw。日常记账的推荐起点是 banking,sales,parties。

未设置范围时，会注册 30 个只读工具。启用某个范围后，只会注册该领域的工具。范围可以叠加，彼此独立；启动时会拒绝未知的范围名称。启用所有写入和删除范围后，最多会注册 126 个工具。

每个可能更改 Manager 的请求都会先经过策略检查。对于访问令牌、科目表、税码、汇率、期初余额、银行对账、自定义字段、电子邮件设置和客户门户等路径的请求，无论启用了哪些范围，都会被永久拒绝。

4. 工具描述

读取工具（默认注册，共 30 个）

• 发现和原始访问：list_resources、list_records、get_record、get_fixed_asset 和 get_server_info（服务器身份、进程、git 状态、已注册工具和当前启用的范围）。
• 旧版报告快捷工具：aged_receivables、aged_payables、bank_balances、trial_balance、profit_and_loss、balance_sheet 和 tax_summary。这些工具返回 Manager 当前状态或原始数据流，并非已完成的报告（参见报告局限性）。
• 报告层（reporting.py）：manager_report_catalogue、get_report_definition、ledger_transactions、reconstructed_trial_balance、reconstructed_profit_and_loss、reconstructed_aged_receivables 和 reconstructed_aged_payables。
• 诊断（diagnostics.py）：find_records、find_broken_invoice_references、find_unallocated_transactions、find_duplicate_transactions、verify_invoice_balance、account_ledger、bank_activity、find_suspense_candidate_accounts 和 general_ledger_summary。
• 对账（reconciliation.py）：reconcile_period。
• corrections.py 中的 list_incomplete_reconstructions：仅从本地审计日志中列出已开始但尚未完成的发票重建尝试。

写入工具（仅在启用相应范围时注册）

• 任务工具（task_tools.py），围绕意图设计，例如 issue_sales_invoice、issue_purchase_invoice、record_customer_payment、record_supplier_payment、record_expense、transfer_between_accounts 和 post_journal_entry。这是推荐的写入方式。
• 每个启用范围都会注册相应资源的 create_* 和 update_* 工具；每个启用的删除范围都会注册 delete_* 工具。create_fixed_asset 和 update_fixed_asset（fixed_assets.py）需要 ledger 范围。
• 更正（corrections.py）：propose_correction 和 apply_correction、适用于采购和销售发票的 propose_*_reconstruction 和 apply_*_reconstruction、reallocate_payment_line 和 reallocate_receipt_line，以及优先于普通 void_document 工具使用的 snapshot_and_void。此处的所有操作都必须先提出方案，再单独执行应用步骤才会写入；每次更正写入都会记录在审计日志中。

每个已注册工具的描述和架构都可通过 MCP 客户端获取；get_server_info 会报告当前启用的工具。

5. 报告的局限性

Manager 的 API 不会返回已完成的报告。报告视图路由仅供应用程序使用，使用 API 密钥访问时会返回 HTTP 401，本项目既不会调用也不会仿造这些路由。报告工具根据 API 实际返回的数据运行，并会标明返回的数据。完整指南见 docs/reporting.md。

• 重建结果绝非权威数据。 reconstructed_trial_balance、reconstructed_profit_and_loss、reconstructed_aged_receivables 和 reconstructed_aged_payables 均由此服务根据 Manager 的账户级分类账计算得出。每项结果都会包含 authoritative: false 和 official_manager_report: false，以及数据来源、计算方法、截止日期和分类账完整性。重建结果与 Manager 中的某个数字一致，并不代表它就是官方数据。
• 重建的账龄结果可能与 Manager 的结果不同。 此处的账龄分析使用交易日期，并按从最早到最新的顺序应用收款；而 Manager 使用到期日和实际分配，因此各账龄区间的金额可能不同。仅会将往来方总额与控制账户总额进行核对。
• 当前状态工具不接受日期。 aged_receivables、aged_payables、bank_balances 和 tax_summary 显示的是截至今天的余额。如果传入日期或期间，工具会拒绝请求，绝不会为过去的日期返回今天的数据。
• 此处会筛选分类账的日期。 Manager 会忽略其 /transactions 分类账数据流上的日期参数，因此服务会获取完整分类账，再自行筛选。结果绝不会被静默截断。分页结果会报告总数和下一位置，数据流则会报告是否完整。
• API 无法提供的内容： Manager 自身的分组和小计布局、过去日期的发票到期日和分配、增值税申报表，以及已完成的报告输出。

在精确性至关重要的情况下，例如增值税或税务申报，请勿将任何报告工具视为 Manager 自身报告的替代品。

6. 许可

Onexur Manager MCP 根据 GNU Affero 通用公共许可证 v3.0 或更高版本（AGPL-3.0-or-later）分发。

本项目整合了 manager-mcp 0.2.6 中的材料，该材料仍根据 MIT 许可证授权。本项目在分发中整合这些材料，不会转让或终止上游衍生部分现有的 MIT 权利和版权；接收者仍享有这些权利。完整的归属声明请参见 NOTICE，有关本仓库中哪些部分源自上游（MIT）、哪些部分由 Xalterra Ltd（以 Onexur 名义经营）原创（AGPL-3.0-or-later）的文件级明细，请参见 PROVENANCE.json。

本项目提供商业许可证，允许在不承担 AGPL 义务的情况下使用 Xalterra Ltd 拥有的 Onexur 代码。许可条款请联系 [email protected]。

完整的 AGPL-3.0-or-later 文本收录于 LICENSE-AGPL，完整的 MIT 许可证文本收录于 LICENSE-MIT。

7. 署名

本项目采用了 manager-mcp 0.2.6 中的材料，该版本依据 MIT License 发布，版权归 manager-mcp 贡献者所有（2026 年）。

本仓库中哪些部分源自上游、哪些部分由 Xalterra Ltd（以 Onexur 名义经营）原创，均按文件详细列于 PROVENANCE.json，并附有易读的摘要 PROVENANCE_SUMMARY.md。上游历史版本说明（版本 0.1.0 至 0.2.6）未经修改，保存在 docs/upstream-history.md 中。当前版本说明见 CHANGELOG.md。

MIT License 的完整文本转载于 LICENSE-MIT。完整的署名声明请参见 NOTICE。

8. 商标免责声明

“Manager”及其相关标志均为各自所有者的商标。本项目是独立的第三方集成，与 Manager 或其发行方无关联，也未获得其认可或赞助。本项目不分发任何 Manager 品牌标识、徽标或专有 API 描述材料。

---

贡献

请参阅 CONTRIBUTING.md 和 CLA.md。对于 PROVENANCE.json 中标记为源自上游的文件，相关贡献仍受上游 MIT license 约束；对于 Onexur 原创文件，相关贡献受本项目的贡献者许可协议（版本 1.0）约束。按照 CONTRIBUTING.md 所述，在拉取请求中发表评论即表示接受该协议。

延伸阅读

• docs/reporting.md：报告与权限指南
• CHANGELOG.md：当前版本说明
• docs/upstream-history.md：上游历史版本说明
• PROVENANCE.json 和 PROVENANCE_SUMMARY.md：按文件列出的许可来源信息
• SECURITY.md：漏洞披露政策