Mercury Invoicing Mcp

🏦 mercury-invoicing-mcp

Mercury Banking MCP 服务，全面支持 Invoicing API——首个开放 Mercury 应收账款接口的 MCP。

一个模型上下文协议（MCP）服务，让 AI 助手（Claude、Cursor、Continue 等）能够通过程序全面访问你的 Mercury 商业银行账户，包括其他所有 Mercury MCP 都缺少的 Invoicing API（一次性和定期发票）。

✨ 为什么选择这个 MCP？

功能	官方 Mercury MCP	dragonkhoi/mercury-mcp	mercury-invoicing-mcp
银行只读（账户、交易、对账单）	✅	✅	✅
银行写入（send_money、收款人）	❌	✅	✅
在自有 Mercury 账户之间内部转账	❌	❌	✅
Invoicing API（创建、更新、取消、附件）	❌	❌	✅
客户应收账款 + 定期发票	❌	❌	✅
Webhook 完整 CRUD（含 update_webhook）	❌	❌	✅
内置安全措施（速率限制、试运行、审计日志脱敏）	❌	❌	✅
稳定令牌（无需频繁重新认证，可设置 IP 允许列表）	❌	✅	✅
开源（MIT）	❌	✅	✅
Node.js 最低版本	不适用（托管）	❌，需 Node 14（已于 2023 年终止支持）	✅ LTS（>=24.18.1），已在 24 和 26 上测试
暴露的工具总数	~10	~11	39

如果仅用于只读查询，请优先选择官方 Mercury MCP。如果你需要自动处理发票、向 Mercury 写入数据，或安全地向大模型 Agent 开放 Mercury，请使用此 MCP。

📦 安装

npm install -g mercury-invoicing-mcp

或直接使用 npx：

npx mercury-invoicing-mcp

⚙️ 配置

服务器会从环境中读取 MERCURY_API_KEY。请前往 Mercury Settings → API Tokens 获取 API 密钥。

🔑 精确设置令牌权限

Mercury 在创建令牌时提供针对每项资源的细粒度权限范围，而不是单一的读写开关。请只选择用例所需的权限，Mercury 会在服务端执行其余限制：调用工具时如果缺少相应权限范围，会返回 403，MCP 会将其呈现为简洁的 isError: true 响应（相关情况下还会附上 Mercury Plus 提示）。

创建令牌时，你可以选择：

• 令牌可查看哪些账户（一个、多个或全部）。
• 每类资源的读取或写入权限：Accounts、Transactions、Recipients、Send Money、Cards、Statements、Treasury、Invoicing (AR)、Webhooks。

此 MCP 的常见权限配置：

用例	授予的权限范围
只读咨询（仪表板、聊天频道机器人）	对 accounts、transactions、statements、cards、treasury 具有读取权限——不授予其他权限
记账（为交易分类）	所有资源均具有读取权限 + 对 transactions 具有写入权限（用于 update_transaction）
发票自动化	对 accounts 具有读取权限 + 对 invoices、customers 具有写入权限（需要 Mercury Plus）
收款人管理	+ 对 recipients 具有写入权限
在自有账户之间进行内部转账	+ 对 send_money 具有写入权限（用于 create_internal_transfer）
发起对外付款请求	+ 对 send_money 具有写入权限（创建请求——请参阅下方安全提示）
仅操作 Webhooks	仅对 webhooks 具有写入权限

⚠️ 重要提示：对外付款取决于你在 Mercury 中设置的审批政策

通过此 MCP 创建的对外付款是立即执行还是等待人工审批，并不由 MCP 控制，而是由 Mercury 工作区的审批政策（app.mercury.com 上的 Settings → Approvals）执行。MCP 只能创建 API 调用；Mercury 如何处理该调用，取决于你的工作区配置。

三个资金工具的行为各不相同：

• mercury_request_send_money——无论工作区政策如何，始终会在 Mercury 中创建一个待审批请求。专为“提交后等待审批人处理”的工作流而设计。
• mercury_send_money——提交一笔付款。根据你的工作区审批规则（金额门槛、特定账户规则、所需审批人），付款会立即执行或进入审批队列。如果工作区的审批门槛设为 $0，则每笔对外付款都需要在 Mercury 网页版或移动应用中等待人工批准。在规则更宽松的工作区中，较小金额的付款可能无需再次确认即可结算。
• mercury_create_internal_transfer——在同一 Mercury 组织内的两个自有账户之间转移资金。没有外部收款人，也不涉及审批流程。

→ 在 Mercury 中设置严格的审批政策（例如，不论金额大小，所有对外付款都必须经过审批），尤其是在计划向 Agent 开放写入工具时。MCP 的单次调用速率限制和试运行模式可提供额外保护，但真正起决定作用的是 Mercury 的审批政策。如果受到提示词注入的 Agent 调用了 send_money，该调用是否安全，完全取决于 Mercury 处理来自任何其他 API 调用方的相同负载时会如何操作。

🧪 沙盒模式

若要在 Mercury 的沙盒环境中测试（不涉及真实资金，并预置了虚拟数据），只需使用沙盒令牌：

MERCURY_API_KEY=secret-token:mercury_sandbox_xxxxxxxxxxxxxxxx

MCP 会自动检测沙盒令牌（以 mercury_sandbox_ 开头），并自动将请求发送到 https://api-sandbox.mercury.com/api/v1。

若要显式覆盖基础 URL（例如，使用可自托管的代理）：

MERCURY_API_BASE_URL=https://your-proxy.example.com/api/v1

🛡️ 位于会自行解析 DNS 的本地代理之后

有些代理会用自己的地址响应 DNS（Surge 在增强模式下会分配 198.18.0.0/15），而 SSRF 防护会拒绝这些地址，正如它会拒绝任何非公网地址一样。如果你信任该代理，可以列出它的地址范围：

MCP_TRUSTED_CIDRS=198.18.0.0/15

以逗号分隔的 IP 或 CIDR 范围；如果代理允许，优先使用单个 IP。以下情况会在启动时被拒绝：格式错误的条目、总计超过 131,072 个地址（单个范围：IPv4 最多 /15，IPv6 最多 /111），以及包含回环地址、链路本地地址、0.0.0.0/8 或携带 IPv4 地址的 IPv6 范围（例如 ::ffff:10.47.83.1 这样的 IPv4 映射地址会按其 IPv4 地址计算）。这些范围内的地址将不再由防护检查：信任责任转移给代理。未设置时：不启用例外。

🤖 Claude Desktop / Claude Code

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（Claude Code 则添加到 ~/.claude.json）：

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:mercury_production_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

🖱️ Cursor

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:..."
      }
    }
  }
}

🦀 OpenClaw

OpenClaw 是一个开源、可自托管的 Agent 平台，通过 @modelcontextprotocol/sdk 支持 MCP。添加到 ~/.openclaw/openclaw.json：

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:..."
      }
    }
  }
}

重启网关（docker restart openclaw-openclaw-gateway-1 或使用等效命令）。所有工具都会对你的所有 OpenClaw Agent 开放。

提示：对于通过不受信任渠道（WhatsApp、Telegram、Slack、来信邮件等）接入的 Agent，只授予令牌该渠道实际需要的权限范围。对外付款仍需在 Mercury 应用中获得人工明确批准；但尽量缩小权限范围可以避免不必要的干扰（虚假的待处理请求），并减少攻击者通过读取操作可能窃取的数据。请参阅按需设置令牌权限，了解各使用场景的配置方法。

🛠️ 工具（共 39 个）

🏦 银行 — 账户

• mercury_list_accounts、mercury_get_account
• mercury_list_cards
• mercury_get_organization
• mercury_list_categories

💳 银行 — IO Credit

• mercury_list_credit_accounts — 封装 GET /credit，对应 Mercury API 参考文档中的Credit › List all credit accounts。返回 IO Credit 卡账户；mercury_list_accounts 会在服务端将其过滤掉。
• mercury_list_credit_transactions — 封装 GET /account/{id}/transactions（单数路径），这是 IO Credit 交易所用的路径，包括待处理的银行卡预授权。注意：这不同于存款账户使用的复数路径 /accounts/{id}/transactions。
• mercury_list_credit_statements — 封装 GET /api/v2/account/{id}/statements。IO Credit 对账单仅由 v2 端点提供：v1 对账单路径对信用账户会返回 404。

💸 银行 — 交易

• mercury_list_transactions、mercury_get_transaction
• mercury_get_transaction_attachment — 唯一会返回收据下载 URL 的工具
• mercury_update_transaction（备注、类别）
• mercury_send_money、mercury_request_send_money
• mercury_create_internal_transfer（在你自己的 Mercury 账户之间转账）

默认情况下，交易列表会返回精简投影：标识字段以及 hasAttachment，方便你找出哪些交易仍缺少收据。在真实账户上测量时，这会将载荷缩减至 Mercury 原始响应的约 20%。传入 detail: "full" 可获取除附件 URL 外的所有字段；任何模式都不会返回附件 URL。

交易载荷中绝不会包含收据 URL，无论使用哪种模式。Mercury 的收据 URL 是预签名 S3 链接，每个约 2.4 kB，并且是一种持有者凭证，可在约 12 小时内免认证访问文档。每次读取都返回一个这样的 URL，不仅会让载荷变得臃肿，还会使短期凭证散落在日志和模型上下文中。如需收据 URL，请通过 mercury_get_transaction_attachment 按交易单独获取。

👥 银行 — 收款人

• mercury_list_recipients、mercury_add_recipient、mercury_update_recipient

📊 银行 — 对账单

• mercury_list_statements

🏛️ 财务管理

• mercury_get_treasury
• mercury_list_treasury_transactions
• mercury_list_treasury_statements

🧾 开票（应收账款）

⚠️ 需要 Mercury Plus 方案。 开票和客户（AR）API 仅适用于 Mercury 的 Plus 方案（或更高级别方案）。在 Free 或 Standard 方案上调用这些工具会返回 403 Forbidden。其他工具（银行业务、财务管理、webhooks）适用于所有方案。

• mercury_list_invoices、mercury_get_invoice
• mercury_create_invoice、mercury_update_invoice
• mercury_cancel_invoice
• mercury_list_invoice_attachments
• mercury_get_invoice_pdf — 通过 Mercury 文档中的 getinvoicepdf 端点（{baseUrl}/ar/invoices/{id}/pdf，需验证身份，兼容沙盒和代理）返回发票 PDF 的下载 URL。与 mercury_list_invoice_attachments 不同，后者只列出手动上传的文件。

👤 客户（AR）——也需要 Mercury Plus

• mercury_list_customers、mercury_get_customer
• mercury_create_customer、mercury_update_customer、mercury_delete_customer

🔗 Webhooks

• mercury_list_webhooks、mercury_get_webhook
• mercury_create_webhook、mercury_update_webhook、mercury_delete_webhook

尚未封装的端点 — Mercury 还提供约 22 个此 MCP 尚未支持的其他端点， 后续版本将逐步加入。 跟踪中的项目：报表 PDF 下载（getstatementpdf——发票 PDF 已由 mercury_get_invoice_pdf 支持）、附件 （uploadtransactionattachment、uploadrecipientattachment、 getattachment、listrecipientsattachments）、webhook 签名 验证（verifywebhook）、webhook 事件（getevent、getevents）、 汇款审批（listsendmoneyapprovalrequests、 getsendmoneyapprovalrequest）、用户（getuser、getusers）、 Mercury Raise SAFE（getsaferequest(s)、getsaferequestdocument）， 以及 OAuth 流程（obtainaccesstoken、startoauth2flow）。

Mercury 完全没有通过公共 API 提供 list_send_money_requests、COA Templates 或 Journal Entries——这些功能只能在控制面板中使用。

不存在 send_invoice 端点（无论是 API 还是控制面板）。 只有在创建发票时将 sendEmailOption: "SendNow" 设为发送邮件， 才会发送发票邮件。之后如需发送副本，请通过 mercury_get_invoice_pdf 获取发票 PDF URL，下载后再手动通过邮件发送。

可用工具取决于你的 Mercury API 令牌范围。服务会注册全部 39 个工具， 但 Mercury 会在 API 层拒绝未授权的操作。

🗺️ 路线图

参见 ROADMAP.md。

🔒 安全

• 切勿分享 API 密钥。 使用环境变量，切勿将密钥作为 CLI 参数传递。
• 不需要写入权限时，请使用只读或限定范围的令牌。
• 向会读取不可信内容的大模型开放写入工具时，请注意提示词注入风险。参见 Anthropic 的 MCP 安全指南。

🛡️ 内置防护措施

此 MCP 包含三层中间件，会自动应用于写入工具（读取工具不受影响）：

1️⃣ 速率限制（双时间窗口）

每个写入工具都映射到一个限额组。每个限额组会同时执行两个滚动时间窗口——每日上限（24 h）和每月上限（滚动 30 天）。任一时间窗口达到上限后，调用就会被拒绝，因此即使失控的 Agent 通过数周内控制调用频率来保持在每日限额以内，也无法耗尽账户额度。

限额组	工具	每日	每月（30 天）
payments	send_money, request_send_money	7	150
internal_transfer	create_internal_transfer	2	40
invoices_write	create_invoice, update_invoice	10	200
invoices_cancel	cancel_invoice	3	30
customers_write	create_customer, update_customer, delete_customer	3	60
recipients_add	add_recipient	3	45
recipients_update	update_recipient	2	15
transactions_update	update_transaction（簿记、标记、收据）	50	500
webhooks_create	create_webhook	2	15
webhooks_update	update_webhook	2	15
webhooks_delete	delete_webhook	2	15

按限额组覆盖设置（必须同时提供两个时间窗口）：

MERCURY_MCP_RATE_LIMIT_payments=15/day,300/month   # larger supplier batch
MERCURY_MCP_RATE_LIMIT_invoices_write=20/day,400/month  # large monthly billing run
MERCURY_MCP_RATE_LIMIT_DISABLE=true                # disable all rate limiting (not recommended)

超出限额时，工具会返回带有结构化 JSON 负载的 isError: true 响应。source 和 error_type 前缀能明确表明这是本地 MCP 防护措施——调用从未发送到 Mercury。真正的 Mercury 429 错误会单独显示为 "Mercury API error 429: ..."。

{
  "source": "mcp_safeguard",
  "error_type": "mcp_rate_limit_daily_exceeded",
  "message": "MCP Rate Limit Exceeded — Daily (local safeguard, not a Mercury API error)",
  "hint": "Daily Limit Exceeded: mercury_send_money (bucket: payments) capped at 7 per 24h. Retry in ~180 min. Override with MERCURY_MCP_RATE_LIMIT_payments=D/day,M/month if this is a legitimate batch.",
  "retry_after": "2026-04-22T00:00:00.000Z"
}

error_type 的值为 mcp_rate_limit_daily_exceeded 或 mcp_rate_limit_monthly_exceeded——Agent 可以根据相应粒度学会退避，不会将 MCP 的本地限额与服务端的 Mercury 限额混淆。

速率限制窗口在进程重启后仍然有效。状态会持久化到 ~/.mercury-mcp/ratelimit.json（模式 0o600）；如果需要在主机之间共享状态，或将其固定到特定卷，可使用 MERCURY_MCP_STATE_DIR=/abs/path 覆盖保存位置。若没有持久化，每个会话都会重新启动服务的 MCP 主机就能悄无声息地绕过限额。

2️⃣ 试运行模式

查看 Agent 会执行哪些操作，而不实际调用 Mercury。适用于调试可疑行为或预演：

MERCURY_MCP_DRY_RUN=true

写入工具随后会返回描述预期操作的结构化负载，而不会调用 Mercury API。

3️⃣ 审计日志（选择启用）

启用对每次写入调用进行结构化 JSON 记录：

MERCURY_MCP_AUDIT_LOG=/var/log/mercury-mcp-audit.log

每行的格式为 {ts, tool, result, args}（每行一个 JSON 对象）。结果为 ok、dry-run 或 error。路径必须是绝对路径；args 中的敏感字段（accountNumber、routingNumber、apiKey、authorization、password、token、secret、ssn）会自动隐藏。文件创建时的模式为 0600（仅所有者可读写）。

🔧 开发

git clone https://github.com/klodr/mercury-invoicing-mcp.git
cd mercury-invoicing-mcp
npm install
npm run build
npm test

💡 灵感来源

• @stripe/mcp — 架构模式
• dragonkhoi/mercury-mcp — 初始银行业务工具实现
• Official Mercury MCP — 只读参考

🌐 生态系统

klodr 家族中的其他 MCP 服务：

• 📧 klodr/gmail-mcp — Gmail
• 📠 klodr/faxdrop-mcp — 通过 FaxDrop 发送真实传真
• 🏦 klodr/mercury-invoicing-mcp — Mercury 银行业务 + 发票（你正在此处）

📄 许可证

MIT — 详见 LICENSE。

🤝 贡献

欢迎提交问题和 PR。测试、构建、覆盖率检查清单及发布流程请参阅 CONTRIBUTING.md。