1. 项目概述与核心价值如果你是一名使用Mercury Banking的创业者、独立开发者或小型企业主并且正在探索如何将AI助手如Claude Desktop、Cursor深度集成到你的财务工作流中那么你很可能已经遇到了一个瓶颈现有的Mercury MCP工具要么功能不全要么缺少你最需要的自动化能力。这正是我着手开发mercury-invoicing-mcp这个开源项目的初衷。作为一个在金融科技和自动化领域摸爬滚打多年的开发者我深知将银行账户与AI代理安全、可控地连接起来对于提升运营效率、减少重复性劳动有多么重要。这个项目不仅仅是一个简单的API包装器它是一个完整的、带有安全护栏的MCP服务器首次将Mercury的完整发票InvoicingAPI和客户应收账款AR功能暴露给AI助手让你能通过自然语言指令管理发票、客户甚至执行内部转账。市面上已有的方案比如官方的Mercury MCP功能仅限于只读查询而另一个开源项目dragonkhoi/mercury-mcp虽然支持部分写入操作但缺少关键的发票API支持并且其依赖的Node.js版本已经停止维护。mercury-invoicing-mcp填补了这些空白它基于最新的Node.js LTS版本构建提供了总计34个工具覆盖了从账户查询、交易分类、收款人管理到发票创建、客户管理以及Webhook全生命周期操作的所有核心场景。更重要的是它内置了多层安全防护机制包括细粒度的速率限制、沙盒模式和审计日志让你在享受自动化便利的同时不必为资金安全提心吊胆。无论你是想通过AI自动生成并发送周期性账单还是想让AI助手帮你整理交易记录、管理收款人这个工具都能提供一个可靠、安全的桥梁。2. 核心功能与差异化优势解析2.1 功能矩阵对比为什么选择它在决定采用一个工具尤其是涉及财务数据的工具时清晰的对比至关重要。下表详细拆解了mercury-invoicing-mcp与市面上其他主流Mercury MCP方案的核心能力差异能力维度官方 Mercury MCPdragonkhoi/mercury-mcpmercury-invoicing-mcp银行数据读取(账户、交易、对账单)✅✅✅银行写入操作(发起付款、管理收款人)❌✅✅账户间内部转账❌❌✅发票API全支持(创建、更新、取消、附件)❌❌✅客户管理与周期性发票❌❌✅Webhook全生命周期管理(含更新)❌❌✅内置安全护栏(速率限制、沙盒模式、审计日志)❌❌✅托管服务(无需管理令牌)✅❌❌开源协议(MIT)❌✅✅Node.js版本要求N/A (托管)❌ (Node 14已停止支持)✅ (Active LTS,22.22.2)暴露工具总数~10~1134从这个对比中可以清晰地看到mercury-invoicing-mcp在功能完备性上具有压倒性优势。它不仅仅是“另一个MCP服务器”而是一个针对自动化场景深度优化的解决方案。官方MCP适合简单的、只读的咨询场景比如在聊天频道里问一句“我账户里还有多少钱”。但当你需要AI真正为你“做事”时——比如“为上周的咨询服务创建一张发票并发送给客户ABC”或者“把运营账户里的5000美元转到税务预留账户”——官方的只读能力就完全不够用了。而dragonkhoi/mercury-mcp项目虽然迈出了写入操作的一步但其依赖的Node 14版本在2023年就已结束生命周期这意味着存在潜在的安全漏洞且缺乏官方支持。更重要的是它完全缺失了Mercury Plus计划用户最关心的发票和客户管理功能。对于许多SaaS或服务型小企业来说发票和应收账款管理是财务工作的核心无法自动化这部分流程AI助手的价值就大打折扣。因此选择mercury-invoicing-mcp的核心理由可以归结为三点功能全面覆盖读写、发票、客户、Webhook、安全可控内置多层防护、面向未来基于现代、活跃的Node.js LTS版本构建。它让你能够放心地将更多财务操作委托给AI代理而无需在功能和安全之间做妥协。2.2 深入理解Mercury API令牌的“权限粒度”一个容易被忽视但至关重要的细节是Mercury API令牌的权限模型。与许多提供简单“读写”开关的API不同Mercury采用了极其精细的、按资源家族划分的权限控制。这意味着你在创建令牌时需要像搭积木一样精确组合出AI助手所需的最小权限集。这不仅是安全最佳实践也是Mercury在服务端强制执行的策略。当你登录Mercury后台在“设置 - API令牌”中创建新令牌时会面临两个维度的选择账户可见性这个令牌能访问你名下的哪些银行账户可以是单个账户、特定几个账户也可以是全部账户。资源操作权限为每个资源家族如账户Accounts、交易Transactions、收款人Recipients、发票Invoicing等分别指定“读取Read”或“写入Write”权限。这种设计带来了巨大的灵活性。例如你可以创建一个专门用于“交易分类”的AI助手只给它Transactions资源的Write权限用于更新交易备注和类别而不给它任何发起付款的权限。这样即使该助手的指令被恶意注入攻击者也无法转走你的资金最多只能把交易记录弄得一团糟。为了帮助你快速配置这里有一些针对常见场景的“权限配方”使用场景建议授予的权限范围只读咨询(仪表板、聊天机器人查询)对accounts,transactions,statements,cards,treasury仅授予Read权限。簿记自动化(AI自动分类交易)对所有资源授予Read权限并额外对transactions授予Write权限用于update_transaction。发票自动化对accounts授予Read权限用于关联发票到账户并对invoices和customers授予Write权限需要Mercury Plus计划。收款人管理在上述基础上增加对recipients的Write权限。内部账户间转账需要send_money的Write权限create_internal_transfer工具会用到。对外付款请求同样需要send_money的Write权限但实际执行受审批策略控制见下文。仅Webhook操作只对webhooks授予Write权限。如果AI助手尝试调用一个其令牌没有权限的工具Mercury API会直接返回403 Forbidden错误。mercury-invoicing-mcp会干净地将这个错误转化为isError: true的响应并附带清晰的错误信息甚至会提示你是否需要升级到Mercury Plus计划。这种清晰的错误反馈机制对于调试和权限管理非常有帮助。2.3 关键安全机制审批策略与内置防护将财务写入权限暴露给AI最大的担忧无疑是资金安全。mercury-invoicing-mcp的设计哲学是“不信任要验证”并通过多层机制来实现这一点。第一道防线Mercury工作区审批策略这是最重要、最权威的安全闸门。无论MCP服务器做了什么最终是否执行一笔对外付款完全由你在Mercury网站上设置的审批策略Settings → Approvals决定。这个策略是工作区级别的独立于任何API调用。零阈值策略如果你设置“任何金额的对外付款都需要审批”那么即使AI助手通过mercury_send_money工具发起了付款这笔交易也会在Mercury后台变为“待审批”状态等待你或指定的审批人在网页或手机App上手动点击批准。在批准前资金不会转出。金额阈值策略你可以设置“超过1000美元的付款需要审批”。那么AI发起的小额付款可能自动执行大额付款则进入审批流程。这里需要区分三个与付款相关的工具mercury_request_send_money这个工具总是在Mercury中创建一个“待审批的付款请求”专为“提交后等待审批人”的工作流设计。mercury_send_money提交一笔付款。它是立即执行还是等待审批完全取决于你的工作区审批规则。mercury_create_internal_transfer在你自己名下的Mercury账户之间转账。不涉及外部收款人因此通常不受审批策略限制但依然受速率限制管控。核心安全建议如果你计划向AI助手开放写入工具强烈建议在Mercury工作区设置一个严格的审批策略例如所有对外付款都需要审批。这样MCP的速率限制和沙盒模式是额外的“安全带”而Mercury的审批流程则是最终的“安全气囊”。第二道防线MCP内置安全护栏即使有审批策略我们也不希望AI助手因为被恶意提示注入而疯狂创建待审批请求造成干扰。因此项目内置了三层防护速率限制双窗口每个写入工具都被分配到一个“桶”bucket每个桶同时强制执行每日24小时滚动和每月30天滚动两个调用上限。一旦任一窗口达到上限后续调用将被立即拒绝且请求不会发送到Mercury API。这防止了AI代理通过“细水长流”的方式在长时间内耗尽限额。限制策略非常细致例如payments桶包含发送付款每日限7次每月限150次而transactions_update桶用于簿记则宽松得多每日50次每月500次。沙盒模式通过设置环境变量MERCURY_MCP_DRY_RUNtrue所有写入工具将进入“演习”模式。AI助手可以正常调用工具并收到一个结构化的响应描述它“将要”执行什么操作但实际的API调用不会被发出。这对于测试AI工作流、调试提示词或进行安全审计极其有用。审计日志可选通过设置MERCURY_MCP_AUDIT_LOG指向一个绝对路径的文件所有写入工具的调用详情时间戳、工具名、参数、结果都会被记录为一行JSON。敏感字段如账号、路由号、API密钥等会被自动脱敏。这个日志文件仅对所有者可读可写为事后审查提供了不可篡改的记录。这些机制共同构成了一个纵深防御体系让你在享受自动化带来的效率提升时能对潜在风险有充分的掌控。3. 环境配置与集成实战3.1 安装与基础配置安装过程非常直接。由于这是一个Node.js包你可以选择全局安装以便在任何地方调用或者使用npx临时运行。# 全局安装推荐便于配置 npm install -g mercury-invoicing-mcp # 或使用npx直接运行无需安装 npx mercury-invoicing-mcp安装完成后核心配置就是设置Mercury API密钥。绝对不要将密钥硬编码在脚本或命令行参数中务必使用环境变量。# 在终端中临时设置仅当前会话有效 export MERCURY_API_KEYyour-secret-api-token-here # 然后运行MCP服务器 mercury-invoicing-mcp你的API密钥可以在 Mercury设置 → API令牌 页面获取。创建时请务必根据上一节提到的“权限配方”精细地勾选所需权限。沙盒环境测试在将工具用于真实资金之前务必在沙盒环境中充分测试。Mercury提供了完整的沙盒环境里面有模拟的账户和交易数据。要使用沙盒只需获取一个沙盒环境的API令牌令牌通常以mercury_sandbox_开头并将其设置为MERCURY_API_KEY的值即可。mercury-invoicing-mcp会自动检测沙盒令牌并将请求指向https://api-sandbox.mercury.com/api/v1。export MERCURY_API_KEYsecret-token:mercury_sandbox_xxxxxxxxxxxxxxxx mercury-invoicing-mcp3.2 与主流AI开发环境集成MCP的魅力在于其协议标准化可以轻松接入各种支持MCP的AI助手和开发环境。以下是几个主流平台的配置方法。Claude Desktop / Claude Code对于使用Anthropic Claude系列产品的用户配置位于一个JSON文件中。macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonLinux/Windows (Claude Code):~/.claude.json你需要在此文件中添加MCP服务器的配置。一个完整的配置示例如下{ mcpServers: { mercury-invoicing: { command: npx, args: [-y, mercury-invoicing-mcp], env: { MERCURY_API_KEY: secret-token:mercury_production_xxxxxxxxxxxxxxxx, MERCURY_MCP_DRY_RUN: false, // 生产环境设为false MERCURY_MCP_RATE_LIMIT_payments: 10/day,200/month // 可选自定义限制 } } } }配置完成后重启Claude Desktop或Claude Code。重启后Claude就能识别并调用所有配置好的Mercury工具了。你可以尝试问它“列出我所有的Mercury银行账户”或“为我创建一个金额为1500美元、描述为‘网站开发尾款’的发票”。CursorCursor是另一款深受开发者喜爱的AI代码编辑器它也原生支持MCP。配置文件的路径是~/.cursor/mcp.json。如果文件不存在创建它即可。{ mcpServers: { mercury-invoicing: { command: npx, args: [-y, mercury-invoicing-mcp], env: { MERCURY_API_KEY: secret-token:... } } } }配置完成后同样需要重启Cursor。之后你就可以在Cursor的聊天界面中让AI助手帮你处理财务任务了。OpenClaw对于追求更高自定义度和可控性的用户 OpenClaw 是一个开源的、可自托管的AI代理平台。它通过modelcontextprotocol/sdk支持MCP。配置位于~/.openclaw/openclaw.json。{ mcpServers: { mercury-invoicing: { command: npx, args: [-y, mercury-invoicing-mcp], env: { MERCURY_API_KEY: secret-token:... } } } }添加配置后需要重启OpenClaw网关服务例如使用Docker Compose部署时运行docker restart openclaw-openclaw-gateway-1。重启后所有配置的Mercury工具将对你的所有OpenClaw代理可用。这对于构建复杂的、多步骤的自动化财务工作流如“每周一生成上周服务报告并创建发票”非常强大。集成注意事项在配置环境变量时尤其是对于像OpenClaw这样可能长期运行的服务考虑使用更安全的方式管理密钥例如从加密的密钥管理服务中读取或者使用配置文件确保文件权限为600。避免在配置文件中明文留下生产环境的密钥。3.3 高级配置自定义速率限制与审计默认的速率限制策略是保守的旨在防止意外滥用。但在某些自动化场景下你可能需要调整这些限制。例如如果你经营一个电商业务每天需要创建大量发票那么invoices_write桶的默认限制10/天可能不够。你可以通过环境变量覆盖任意桶的限制格式为MERCURY_MCP_RATE_LIMIT_bucket_namedaily_limit/day,monthly_limit/month。必须同时提供每日和每月限制。# 在启动命令前设置环境变量 export MERCURY_MCP_RATE_LIMIT_invoices_write50/day,1000/month export MERCURY_MCP_RATE_LIMIT_payments20/day,300/month mercury-invoicing-mcp如果你完全信任你的自动化流程和AI代理并希望禁用速率限制不推荐可以设置export MERCURY_MCP_RATE_LIMIT_DISABLEtrue审计日志是另一个强大的运维工具。启用后所有写入操作都会被记录。这对于合规性检查、调试异常行为或 simply keeping a trail of what the AI did非常有用。# 指定一个绝对路径来存储审计日志 export MERCURY_MCP_AUDIT_LOG/var/log/my-app/mercury-audit.log # 确保该目录存在且MCP进程有写入权限 mkdir -p /var/log/my-app touch /var/log/my-app/mercury-audit.log chmod 600 /var/log/my-app/mercury-audit.log审计日志文件会自动以0600权限创建确保只有文件所有者可以读写。每行都是一个JSON对象包含了时间戳、工具名、参数已脱敏和结果状态ok,dry-run,error。4. 工具详解与实战应用场景mercury-invoicing-mcp暴露的34个工具可以大致分为几个功能模块。理解每个模块的用途和典型场景能帮助你更好地设计AI工作流。4.1 银行与交易管理模块这个模块提供了对Mercury银行核心功能的访问是构建财务仪表板或交易分析AI助手的基础。账户与组织信息(mercury_list_accounts,mercury_get_account,mercury_get_organization): 获取账户列表、详情以及公司信息。常用于开场查询让AI了解上下文。交易查询与更新(mercury_list_transactions,mercury_get_transaction,mercury_update_transaction): 核心工具。update_transaction允许AI修改交易的备注note和类别category这是实现“AI自动簿记”的关键。例如你可以训练AI识别“Stripe”或“AWS”的交易并自动将其归类为“收入”或“云服务”费用。收款人管理(mercury_list_recipients,mercury_add_recipient,mercury_update_recipient): 管理你的付款对象。AI可以根据聊天记录或邮件自动将新的供应商添加为收款人为后续付款做准备。内部转账(mercury_create_internal_transfer): 这是一个非常实用的工具用于在你自己名下的不同Mercury账户之间调配资金。例如“将运营账户中的2000美元转到税务储蓄账户”。一个实战场景AI自动交易对账假设你每周都需要手动检查信用卡交易并将其与Mercury账户的扣款进行对账。你可以构建一个AI工作流AI调用mercury_list_transactions获取最近一周的交易。对每笔交易AI分析描述信息调用mercury_update_transaction为其添加更清晰的备注如“AWS US-EAST-1 服务器费用”并分配正确的类别如“技术基础设施”。对于无法自动识别的交易AI可以生成一个待办列表供你稍后手动处理。 这个过程可以完全通过自然语言指令触发大大节省了每周重复劳动的时间。4.2 发票与客户管理模块需Mercury Plus这是本项目的王牌功能也是区别于其他MCP的核心。请注意发票和客户API需要你的Mercury账户升级到Plus或更高计划。发票全生命周期(mercury_list_invoices,mercury_get_invoice,mercury_create_invoice,mercury_update_invoice,mercury_cancel_invoice): 支持创建、查看、更新和取消发票。创建发票时可以指定客户、金额、描述、税费、截止日期等并选择是否立即发送邮件。客户管理(mercury_list_customers,mercury_get_customer,mercury_create_customer,mercury_update_customer,mercury_delete_customer): 管理你的应收账款客户。可以与发票工具联动。一个实战场景基于项目管理的自动开票假设你使用某个项目管理工具如Linear, Jira或时间追踪工具如Toggl。你可以构建一个集成在项目里程碑完成或每月底时外部系统触发一个事件调用你的AI代理。AI代理根据项目ID从数据库或外部API获取服务详情、工时和费率。AI首先检查客户是否存在mercury_list_customers如果不存在则创建mercury_create_customer。AI调用mercury_create_invoice填入所有详细信息并设置sendEmailOption: SendNow一键生成并发送发票给客户。AI将发票状态和链接记录回项目管理工具。 整个过程无需人工干预实现了从交付到开票的端到端自动化。重要提示关于发送发票。Mercury API没有独立的“发送发票”端点。发票邮件仅在创建发票时通过sendEmailOption参数选择SendNow来触发。如果需要事后重发目前需要通过Mercury网页界面手动操作或者使用尚未在本MCP中封装的getinvoicepdf端点下载PDF后手动发送。这是Mercury API本身的限制。4.3 Webhook与系统集成模块Webhook是现代应用集成的血脉。这个模块允许AI助手动态管理你的Mercury Webhook。全CRUD操作(mercury_list_webhooks,mercury_get_webhook,mercury_create_webhook,mercury_update_webhook,mercury_delete_webhook): 特别是update_webhook允许你修改已有的Webhook配置如URL、事件类型而无需删除重建。这在调试或切换接收端点时非常方便。实战场景动态事件订阅你的业务逻辑可能在不同阶段需要监听不同的事件。例如在报税季你可能想临时订阅所有“交易创建”事件以便实时导入会计软件。你可以让AI助手执行“为我的生产环境API端点创建一个监听所有交易事件的Webhook”。报税季过后再让AI将其删除或更新为仅监听关键事件。这种动态管理能力让系统集成更加灵活。4.4 未覆盖的端点与未来展望目前mercury-invoicing-mcp封装了34个最核心的端点。Mercury公开API中还有大约23个端点尚未覆盖例如PDF下载getinvoicepdf,getstatementpdf、附件上传、Webhook签名验证、付款审批请求查询等。这些功能已在项目的路线图ROADMAP.md中会在后续版本中陆续加入。需要明确的是有些功能如list_send_money_requests、会计科目模板、日记账分录是Mercury仪表板独有的并未通过公开API暴露因此任何MCP服务器都无法提供。5. 开发、贡献与安全实践5.1 本地开发与测试如果你想深入了解项目内部机制进行二次开发或者为项目贡献代码本地开发环境搭建非常简单。# 克隆仓库 git clone https://github.com/klodr/mercury-invoicing-mcp.git cd mercury-invoicing-mcp # 安装依赖 npm install # 构建项目TypeScript编译为JavaScript npm run build # 运行测试套件 npm test项目使用Vitest作为测试框架并集成了Codecov进行代码覆盖率检查。在提交PR前请确保所有测试通过并且新代码有相应的测试覆盖。详细的贡献指南请参考项目根目录下的CONTRIBUTING.md文件。5.2 安全最佳实践总结在金融自动化领域安全无小事。以下是使用mercury-invoicing-mcp时必须牢记的安全守则最小权限原则为每个AI助手或使用场景创建独立的、权限最少的API令牌。永远不要使用拥有全部权限的“万能钥匙”。善用审批策略在Mercury工作区设置严格的付款审批规则。这是防止资金意外转出的最终屏障。启用内置防护不要禁用默认的速率限制。根据你的业务量适当调高限制但永远保留这层防护。对于生产环境考虑启用审计日志。隔离运行环境如果可能将运行MCP服务器的环境与面向公网的服务隔离。避免在可能被攻击的服务器上运行含有高权限令牌的MCP服务。警惕提示词注入当AI助手能读取不受信任的内容如用户上传的文件、来自互联网的网页时存在被恶意指令误导的风险提示词注入。遵循 Anthropic的MCP安全指南 仔细设计你的系统提示词和工具调用逻辑考虑对AI的输入进行清洗或限制。定期审查审计日志如果启用了审计日志定期检查其内容确认所有操作都符合预期。5.3 故障排查与常见问题在实际使用中你可能会遇到一些问题。这里是一些常见情况的排查思路工具调用返回isError: true检查错误信息错误信息会明确指示原因。如果是403 Forbidden说明API令牌权限不足。如果是MCP Rate Limit Exceeded则是触发了内置速率限制。确认Mercury计划如果错误提示与发票或客户相关请确认你的Mercury账户已升级到Plus或更高计划。验证令牌有效性确保MERCURY_API_KEY环境变量设置正确且令牌未过期或被撤销。AI助手无法识别MCP工具检查配置文件路径和格式确保Claude Desktop、Cursor或OpenClaw的配置文件路径正确JSON格式无误。重启客户端修改MCP配置后必须完全重启AI客户端Claude Desktop, Cursor等新的配置才会被加载。查看客户端日志大多数MCP客户端在启动时会输出日志显示加载了哪些MCP服务器。检查日志中是否有关于mercury-invoicing-mcp的错误信息。沙盒模式不生效确保你使用的是以mercury_sandbox_开头的沙盒API令牌。生产令牌在沙盒环境下会返回错误。检查是否意外设置了MERCURY_API_BASE_URL覆盖了自动检测的逻辑。速率限制状态丢失速率限制状态默认持久化在~/.mercury-mcp/ratelimit.json。如果你在多台机器或容器中运行且需要共享状态可以通过设置MERCURY_MCP_STATE_DIR环境变量来指定一个共享的存储路径例如网络存储卷。这个项目源于我个人在尝试自动化小公司财务流程时遇到的诸多不便。现有的工具要么太简单要么不安全要么维护状态堪忧。于是我决定自己动手构建一个既功能强大又让人放心的工具。在开发过程中我特别注重那些“非功能性需求”——安全、可观测性、易配置性。因为我知道一个涉及真金白银的工具稳定可靠比炫酷的功能更重要。经过几个月的迭代和社区反馈mercury-invoicing-mcp已经逐渐成熟。但我认为它最大的价值不在于它现在能做什么而在于它提供了一个安全、可扩展的基石。你可以基于它结合其他MCP工具比如操作数据库的、发送邮件的构建出极其复杂的自动化工作流。例如一个监听客户支持工单的AI在问题解决后自动创建发票或者一个监控账户余额的AI在低于阈值时自动从储蓄账户转入运营账户。最后分享一个小心得在将任何写入工具开放给AI之前一定要在沙盒环境中用真实的业务逻辑完整跑通几次。用MERCURY_MCP_DRY_RUNtrue模式观察AI的行为确认它生成的API调用参数符合你的预期。然后在Mercury后台设置好严格的审批策略再切换到生产环境。这种“先演习后实战”的方法能帮你规避掉绝大多数潜在问题。