monarch-mcp2-obot

一个用于在 obot 之后自托管的单租户 Monarch Money MCP 服务器，从 erikrubstein/monarch-mcp2 分叉而来（它本身并不是更常见的 robcerda/monarch-mcp-server 家族的分叉——它是一个独立实现，由自己的 API 客户端 monarch-api2 提供支撑）。

这个分叉的存在出于上游未涵盖的三个原因：

1. 移植到 MCP Python SDK v2（MCPServer，而不是已弃用的 v1 FastMCP）。

2. 专为 obot 构建的登录工作流：凭据作为环境变量一次性配置，并可选择提供 TOTP 种子支持，从而可以自动解决验证器应用 MFA 挑战——无需浏览器、无需操作系统钥匙串、无需手动抄写 6 位验证码。

3. 刻意保持单租户：每个运行实例恰好对应一个 Monarch 账户。任何工具调用都无法针对其他账户的会话，即使客户端尝试发送这样的调用也不行——请参阅下文“刻意单租户”。

与 Monarch Money 无关联、未获其认可，也不受其支持。

从上游继承的内容

14 个组中共有 125 个工具——accounts, transactions, budget, cashflow, categories, goals, household, investments, merchants, receipts, recurring, reports, tags——与 monarch-mcp2 保持一致，未作任何更改。请参阅其工具列表和设计说明，了解涵盖了什么以及哪些被刻意排除在范围之外（交易规则与自动化、提供商账户连接流程、账户管理的边缘情况）。

Related MCP server: monarch-mcp

此处的不同之处

认证：auth_login、auth_status

在上游的 auth_create_session / auth_save_session / auth_load_session（这些仍然可用，用于完全手动的一次性登录）之上，新增了两个工具：

• auth_login——如果服务器的环境中配置了 MONARCH_EMAIL / MONARCH_PASSWORD（以及用于验证器应用 MFA 的 MONARCH_TOTP_SECRET），则无需任何参数。它会通过从种子计算当前验证码来自动处理 MFA 挑战。也可以显式传入 email / password / totp_secret / mfa_code 来覆盖配置，以便在不改动服务器配置的情况下进行一次性登录。

• auth_status——报告会话是否存在且当前是否有效（默认只进行一次轻量级 API 调用），并且绝不会返回会话令牌。

如果配置了凭据，服务器还会在启动时自动尝试此登录——这种尝试是尽力而为的、非致命的，因此密码错误或网络不可用不会阻止服务器启动；auth_status 和 auth_login 仍然可以用来诊断和重试。

TOTP 种子：与验证器应用注册时使用的那个 base32 密钥相同（也就是你通过扫描二维码获得的内容）。Monarch 会在你启用验证器应用 MFA 时显示一次该种子——请在那时保存它，否则你需要禁用并重新启用 MFA 才能获得一个新的种子。这仅适用于你账户的 MFA 方式是验证器应用的情况；邮箱验证码 MFA 无法以这种方式自动化（没有可用于计算验证码的种子），仍然需要人工通过 auth_login 的 mfa_code 参数来传递新的验证码。

刻意单租户

session_path 存在于每个底层函数上（这是 monarch-api2 的约定），但在向 MCP 客户端暴露之前，它会从每个工具的公共 schema 中被移除——参见 tool_metadata.py。一个部署、一个 Monarch 账户、一个会话文件，通过 MONARCH_SESSION_PATH / MONARCH_CONFIG_DIR 一次性选定。这不仅仅是一个配置默认值：按设计，任何工具调用都无法按请求覆盖它，即使客户端非要发送一个也不行（参见 tests/test_server.py::test_tool_call_ignores_session_path_even_if_a_client_sends_it）。

针对 obot 两种部署模型的传输方式选择

obot 以两种与这里相关的方式支持 MCP 服务器：基于命令/uvx 的方式（stdio）和基于 Docker 的方式（一个端口加一个 streamable-http 端点）。两者都通过 MCP_TRANSPORT 支持（默认 stdio）；Docker 镜像默认将其设置为 streamable-http。参见 config.py / server.py。

环境变量

请像对待任何其他机密一样对待 MONARCH_PASSWORD 和 MONARCH_TOTP_SECRET——obot 的单用户 MCP 服务器模型会在管理员配置服务器时将这类字段标记为“敏感”；请利用这一点。

运行

obot，基于命令/uvx（stdio）

uvx --from git+https://<your-fork-url> monarch-mcp

（一旦你把这个分叉推送到某个地方——请参阅本 README 末尾关于此代码当前存放位置的说明。）

obot，基于 Docker（streamable-http）

docker build -t monarch-mcp2-obot:local .
docker volume create monarch-session

docker run -d --rm \
  -p 8000:8000 \
  -v monarch-session:/data \
  -e MONARCH_EMAIL=you@example.com \
  -e MONARCH_PASSWORD=... \
  -e MONARCH_TOTP_SECRET=...  `# omit if your account doesn't use authenticator-app MFA` \
  monarch-mcp2-obot:local

将 obot 基于 Docker 的 MCP 服务器配置指向此容器在 8000 端口上的 streamable-http 端点。会话状态保存在 monarch-session 卷中，因此在容器重启和重新部署后仍然保留，无需重新登录。

本地开发（stdio，无 Docker）

uv sync
uv run monarch-mcp

测试

uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run mypy src/monarch_mcp/auth_runtime.py src/monarch_mcp/config.py \
  src/monarch_mcp/server.py src/monarch_mcp/groups/auth.py src/monarch_mcp/tool_metadata.py

（mypy --strict 的范围仅限于本分叉编写或实质性更改的文件；从上游继承的组模块并未作为本分叉的一部分重新进行严格类型检查审计——参见 ROADMAP.md。）

代码目前存放的位置

该项目已在本地构建并验证（安装、测试和运行——两种传输方式——均与真实的 MCP initialize 握手对接），但作为此项工作的一部分，尚未推送到托管的 git 远程仓库。在将 uvx --from git+... 指向它之前，请先推送到你自己的分叉/远程仓库；如果你从该远程仓库而不是本地检出构建，请相应更新上面的 Docker 构建说明。

许可证

MIT，继承自上游。参见 LICENSE。