moneybird-mcp

用于 Moneybird 会计 API 的 Model Context Protocol 服务器。

它将 Moneybird 暴露为一组 MCP 工具，因此像 Claude 这样的助手可以查找联系人、读取发票、查看银行流水、记录时间并从你的账套中拉取报表。在你开启写入之前，访问是只读的；工具被分组为可以单独启用的工具集；客户端会自行控制请求节奏，以保持在 Moneybird 的速率限制之内。它对本地客户端使用 stdio，对远程客户端使用 Streamable HTTP。

快速开始

向你的客户端注册服务器。对于 Claude Code：

claude mcp add moneybird -- npx -y moneybird-mcp serve

然后让你的助手连接。服务器无需凭据即可启动，并暴露一个 connect_moneybird 工具：它会在你的浏览器中打开 Moneybird 的令牌页面，要求你提供在那里创建的令牌，验证该令牌，选择你的账套并存储它——全程无需离开对话。

这需要一个支持 MCP elicitation 的客户端。在无法使用该功能的情况下，同样的设置流程可以在终端中运行：

npx moneybird-mcp login

它会引导你完成相同的步骤，并将结果存储在 ~/.config/moneybird-mcp/credentials.json。

在依赖它之前，请检查一切是否都正常：

npx moneybird-mcp status

status 会打印已启用的工具集、写入和删除设置、凭据的来源，以及该令牌可以访问的账套。当无法访问 Moneybird 时，它以非零状态退出。

Related MCP server: kalender.digital MCP Server

身份验证

Moneybird 提供两种获取令牌的方式，本服务器都支持。两种方式都不是完全无需手动操作的：Moneybird 既不支持 Dynamic Client Registration，也不支持 PKCE，因此不存在可以跳过创建令牌或注册应用的流程。这是 Moneybird API 的限制，而不是本服务器的限制。connect_moneybird 工具所做的是移除围绕这一步骤的所有其他环节——它会打开正确的页面，并为你捕获结果。

个人 API 令牌。 你可以自己在 https://moneybird.com/user/applications/new 创建它，勾选你想要的作用域，然后将其粘贴到 moneybird-mcp login。这是最简单的途径。这些作用域在创建时固定不变，Moneybird 目前也不会让这些令牌过期——这也意味着它们无法自动轮换。请像对待密码一样对待它。

OAuth 应用。 你在同一位置注册一个应用，然后：

export MONEYBIRD_CLIENT_ID=...
export MONEYBIRD_CLIENT_SECRET=...
npx moneybird-mcp login --oauth

服务器会打开 Moneybird 的授权页面，在 http://127.0.0.1:51739/callback 捕获重定向，并交换授权码。Moneybird 会精确匹配重定向 URI，因此该 URI 必须原样注册到你的应用中。使用 --port 可以选择其他端口，或使用 --oob 让 Moneybird 在浏览器中显示授权码而不是重定向——在无法打开回环监听器的情况下很有用。OAuth 令牌可以在 Moneybird 中撤销，并且在带有过期时间时会自动刷新。

要在没有任何提示的情况下存储令牌，例如在配置脚本中：

npx moneybird-mcp login --token "$MONEYBIRD_TOKEN"

moneybird-mcp logout 会删除已存储的文件。对于 OAuth 凭据，它不会撤销授权本身——请在 Moneybird 中执行该操作。

有关作用域、刷新行为以及具体流程，请参阅 docs/authentication.md。

配置

配置来自环境；CLI 标志会覆盖它。

环境变量

命令

标志

工具集

工具按照 Moneybird 自己的领域进行分组。默认启用五个；另外四个需要手动启用。

可以显式设置它们、在默认集基础上添加，或从默认集中减去：

moneybird-mcp serve --toolsets core,invoicing     # exactly these two
moneybird-mcp serve --toolsets all                # everything
moneybird-mcp serve --toolsets reports            # exactly reports
moneybird-mcp serve --toolsets -banking,-time     # the defaults minus two

列表中的任何 -name 条目都表示该列表从默认集开始，而不是从零开始。all 优先于所有其他项。未知名称是错误，而不是静默的无操作。

完整的逐工具列表见 docs/tools.md，或运行 moneybird-mcp tools。

安全模型

每个工具都声明了三种访问级别之一，服务器只注册当前设置允许的那些工具。未注册的工具对模型不可见——它不会被误调用，也无法被诱导而凭空产生。

• read — 始终注册。

• write — 创建或修改数据。需要 --allow-write 或 MONEYBIRD_ALLOW_WRITE=true。

• destroy — 需要 --allow-delete 和 --allow-write。单独的 --allow-delete 不起作用。

删除与写入分开受控，因为这两种故障模式不可相提并论。一次错误的写入会留下可纠正的记录；而删除或发送给客户的发票，是 API 无法撤回的。启用写入以便助手起草发票，不应同时也让它删除你的账簿。因此，destroy 级别同时涵盖删除和实际上不可逆的调用，例如向联系人发送文档。

默认情况下为只读。只开启你所需的最小权限：

claude mcp add moneybird --env MONEYBIRD_ALLOW_WRITE=true -- npx -y moneybird-mcp serve

客户端设置

Claude Code

claude mcp add moneybird -- npx -y moneybird-mcp serve

如需写入权限和更广泛的工具选择：

claude mcp add moneybird \
  --env MONEYBIRD_ALLOW_WRITE=true \
  --env MONEYBIRD_TOOLSETS=all \
  -- npx -y moneybird-mcp serve

Claude Desktop

将服务器添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "moneybird": {
      "command": "npx",
      "args": ["-y", "moneybird-mcp", "serve"],
      "env": {
        "MONEYBIRD_ALLOW_WRITE": "true"
      }
    }
  }
}

该文件位于 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json 和 Windows 的 %APPDATA%\Claude\claude_desktop_config.json。编辑后请重启应用。

任意 stdio 客户端

该服务器是一个普通的 stdio MCP 服务器。运行 moneybird-mcp serve，并通过 stdin 和 stdout 进行 JSON-RPC 通信。诊断信息发送到 stderr，绝不发送到 stdout。

{
  "command": "npx",
  "args": ["-y", "moneybird-mcp", "serve"],
  "env": {
    "MONEYBIRD_API_TOKEN": "..."
  }
}

如果你不希望将凭据存储在磁盘上，请在客户端的 env 块中设置 MONEYBIRD_API_TOKEN。它的优先级高于 credentials.json 中的任何内容。

Docker 与自托管

docker build -t moneybird-mcp .
docker run --rm -p 3000:3000 -e MONEYBIRD_API_TOKEN=... moneybird-mcp

该镜像默认采用位于 0.0.0.0:3000 的 HTTP 传输，并暴露 /mcp，以及一个无需认证的 /healthz。未经认证，切勿将其部署到公共地址。

docs/hosting.md 介绍了三种 HTTP 认证模式、多租户 passthrough 部署、反向代理说明以及如何连接远程客户端。

速率限制

Moneybird 允许 每个 IP 每 5 分钟 150 次请求，对于 /reports 端点为 每 5 分钟 50 次。客户端为这两个预算分别维护自己的滑动窗口计数器，并会延迟可能超限的请求，因此正常使用不会出现 429 响应。当 Moneybird 仍然返回 429 时，客户端会遵守 Retry-After，否则以完全抖动（full jitter）的方式指数退避，最多重试 MONEYBIRD_MAX_RETRIES 次。

预算按 IP 计算，而非按 token 计算。位于同一出口地址后面的多个实例共享该预算，而本地计数器无法相互感知。请据此规划部署规模。

开发

npm install
npm run build      # before typecheck: the docs generator imports the built output
npm run typecheck
npm test
npm run format

docs/tools.md 由工具定义生成。添加或更改工具后请重新生成：

npm run docs:tools

spec/endpoints.json 固定了 Moneybird 发布的操作列表，测试会检查工具调用的每个路径是否与之匹配。当 Moneybird 发布 API 变更时，请刷新该文件：

npm run spec:refresh
npm test

刷新后端点测试失败，意味着某个工具依赖的路由已移动或被移除。

贡献

欢迎在 https://github.com/HalloSouf/moneybird-mcp 提交 Issue 和 Pull Request。请先运行 npm run typecheck、npm test 和 npm run format:check 再提交 Pull Request；CI 会在 Node 20 和 22 上运行相同的检查。

许可证

MIT。参见 LICENSE。