robcerda/monarch-mcp-server

Monarch Money MCP 服务器

这是什么 – 一个小型 Python 服务器，与 Monarch Money 个人财务 API 通信，并通过 Model Context Protocol（MCP）公开数据。MCP 是 Claude Desktop、Claude Code 等基于 Anthropic 的 AI 代理调用外部工具的方式。通过运行此服务器，您可以让人工智能读取和修改您的 Monarch 账户、交易、预算、标签等。

为什么重要 – 如果您将 Claude 用作个人助理（例如 Claude Desktop、Claude Code、Meta Muse），并希望它直接以编程方式访问您的银行/预算数据，那么此服务器就是桥梁。它处理 Monarch 棘手的 MFA/登录流程，并提供一套清晰的命令供 AI 调用。

主要功能（按 README 列出的）

账户管理 – 列出账户、持仓，触发刷新。
交易 CRUD – 获取、创建、更新、删除、批量分类、标记标签以及标记为已审核。
类别和标签处理 – 列出类别、组、标签；创建新标签。
搜索与筛选 – 支持日期、金额、商家、标签等条件的强大交易搜索。
定期预测和同步账单 – 查看即将发生的定期付款和负债账单详情。
规则引擎 – 列出/创建/更新/删除自动分类规则。
多种传输选项 – 作为简单的基于 stdio 的工具运行（默认），或公开 Streamable-HTTP 端点（/mcp）。
容器支持 – 基于 Astral 的 uv/Python 3.12 slim 的 Docker 镜像，带有用于会话的持久卷。
集成说明 – 适用于 Claude Desktop/Code、Meta Muse 以及任何 MCP 兼容客户端。

快速入门（本地）

克隆并安装

git clone https://github.com/robcerda/monarch-mcp-server.git
cd monarch-mcp-server
uv sync --locked   # 或 pip install -r requirements-lock.txt && pip install -e .

配置 Claude 客户端 – 添加一个指向 uv run … monarch-mcp-server 命令的 mcpServers 条目（macOS 和 Windows 上的路径不同；请参阅 README 获取准确 JSON）。
进行一次身份验证
```
uv run python login_setup.py   # 或 python login_setup.py
```
该脚本允许您：
- 粘贴浏览器会话 cookie（推荐 – 可避免 Cloudflare CAPTCHA）。
- 使用电子邮件/密码 + MFA 登录。
- 使用旧版令牌（如果有）。生成的会话令牌存储在您的操作系统密钥环中（或 Docker 容器内的文件中）。
重启 Claude – AI 现在将看到一个新的“Monarch Money”工具，包含 get_accounts、get_transactions 等命令。

容器化部署

构建：docker build -t monarch-mcp-server .

身份验证（一次）使用持久卷：

docker run --rm -it -v monarch-session:/home/app/.monarch-mcp-server \
    monarch-mcp-server python login_setup.py

运行服务器（HTTP 模式，默认只读）：

docker run -d --name monarch-mcp \
    -p 127.0.0.1:8000:8000 \
    -v monarch-session:/home/app/.monarch-mcp-server \
    monarch-mcp-server

客户端连接到 http://127.0.0.1:8000/mcp。

启用写入（如果暴露则危险）：添加 -e MONARCH_MCP_READ_ONLY=0。
安全提示 – 会话卷在 Linux 容器上存储未加密的 Monarch 令牌；请将卷视为机密，并在使用完毕后删除。

安全与操作说明

单账户服务器 – 所有连接的客户端共享同一 Monarch 会话。除非放在经过身份验证的反向代理后面，否则不要公开暴露 HTTP 端点。
主机/来源检查 – 可以通过 MONARCH_MCP_ALLOWED_HOSTS 将服务器限制为特定的 Host 头，以缓解 DNS 重绑定攻击。
默认为只读 – Docker 镜像以只读模式运行；仅当 MONARCH_MCP_READ_ONLY=0 时才注册更改命令（包括登录/注销）。
凭据存储 – 在本地安装中，会话保存在操作系统密钥环中；在 Docker 中，它回退到纯文件（仅在 Windows 上通过 DPAPI 加密）。请保持卷私有。
MFA 处理 – 登录脚本支持 TOTP 代码，如果 Monarch 要求，将提示输入验证码。

谁可能使用这个

Claude 的高级用户 – 希望 AI 助手管理预算、对支出进行分类或按需提取交易数据的用户。
构建自定义 AI 代理的开发者 – 需要可靠的、MCP 兼容的个人财务数据端点的开发者。
熟悉一定命令行/Docker 工作且信任上述安全模型的任何人。

底线 – Monarch Money MCP 服务器是一个专用桥梁，允许 Claude 风格的人工智能代理通过标准协议与您的 Monarch 金融数据交互，提供本地和容器化部署选项，并提供关于身份验证和安全的清晰指导。