Monarch MCP Server

Monarch Money MCP 服务

通过 MCP，使用 AI 助手读取并更新你的 Monarch Money 账户、交易和预算。

为什么有这个分支？

这次 FastMCP 重写为 colvint 的原始服务添加了以下工具：

• 搜索与批量编辑： search_transactions 查找商户或关键词；update_transactions_bulk 并行编辑交易，并给出每项结果。
• 支出分析： get_spending_summary 按类别、账户或月份汇总总额；analyze_spending_patterns 对比各月情况。
• 一次调用概览： get_complete_financial_overview 整合账户、预算、现金流、交易和类别。
• 拆分与定期计划： 读取并替换交易拆分，查看计划内发生项，并编辑商户范围的重复规则。

与原始版本和 keithah 的增强型 Python 分支不同，本服务还提供：

• 类型化结果： 带 outputSchema 的结构化输出，并提供文本回退。
• MCP 资源和提示词： 账户/类别/机构资源，按账户划分的持仓/历史记录模板，以及带参数补全的引导式提示词。
• 助手友好调用： 紧凑的交易/类别记录，自然语言日期，读/写标签，以及批量分析的进度提示。

对比信息核对于 2026 年 9 月 14 日。其他分支在金融工具上有所重叠；增强型 Python 分支暴露了更广泛的库 API。本项目聚焦于分析工作流和 MCP 集成，而不是暴露每一个 API 方法。请参阅工具目录。

设置

安装 uv，然后配置你的 MCP 客户端以运行 uvx monarch-mcp-jamiew。你需要 Monarch 邮箱和密码，以及用于基于 TOTP 的双重验证的 MFA 密钥。

这些功能包含在 0.5.2 中，可通过 PyPI 获取。

标准配置

对于带有 mcpServers 配置的客户端：

{
  "mcpServers": {
    "monarch-money": {
      "command": "uvx",
      "args": ["monarch-mcp-jamiew"],
      "env": {
        "MONARCH_EMAIL": "[email protected]",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

claude mcp add monarch-money \
  -e [email protected] \
  -e MONARCH_PASSWORD=your-password \
  -e MONARCH_MFA_SECRET=your-mfa-secret-key \
  -- uvx monarch-mcp-jamiew

codex mcp add monarch-money \
  --env [email protected] \
  --env MONARCH_PASSWORD=your-password \
  --env MONARCH_MFA_SECRET=your-mfa-secret-key \
  -- uvx monarch-mcp-jamiew

[mcp_servers.monarch-money]
command = "uvx"
args = ["monarch-mcp-jamiew"]
env = { MONARCH_EMAIL = "[email protected]", MONARCH_PASSWORD = "your-password", MONARCH_MFA_SECRET = "your-mfa-secret-key" }

mcp_servers:
  monarch-money:
    command: uvx
    args: ["monarch-mcp-jamiew"]
    env:
      MONARCH_EMAIL: "[email protected]"
      MONARCH_PASSWORD: "your-password"
      MONARCH_MFA_SECRET: "your-mfa-secret-key"

git clone https://github.com/jamiew/monarch-mcp
cd monarch-mcp
uv sync --locked

{
  "mcpServers": {
    "monarch-money": {
      "command": "/abs/path/to/uv",
      "args": ["--directory", "/abs/path/to/monarch-mcp", "run", "python", "server.py"],
      "env": {
        "MONARCH_EMAIL": "[email protected]",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

说明

claude mcp add 和 codex mcp add 命令可能会将凭据保存在 shell 历史记录中。请直接编辑客户端的配置文件以避免此问题，并保护好配置文件。

获取你的 MFA 密钥

1. 前往 Monarch Money 设置并启用 2FA
2. 当显示二维码时，寻找“无法扫描？”或“手动输入”
3. 复制 TOTP 密钥，而不是不断变化的六位验证码
4. 将其用作你的 MONARCH_MFA_SECRET

工具

该服务公开以下 29 个工具。

对待处理交易使用 is_pending=True，对已入账交易使用 False；省略则两者都包括。单个和批量更新都接受来自 get_household_members 的 owner_user_id。空字符串设置为共享归属；省略/null 则保持归属不变。分配会覆盖继承的归属。使用 verbose=True 检查 ownedByUser；更新响应不包含它。

规则默认每页 25 条（最多 100）；历史默认 100（最多 1,000）。使用 limit、offset 和返回的 next_offset 继续；total_count 涵盖所有匹配记录。规则详情在 verbose=True 时仍然可用。

规则可以设置类别、商户名称、标签或审核状态。它还可以从报告中隐藏交易。每条规则必须查找商户名称、对账单文本或金额。Monarch 会忽略对不满足此条件的规则的编辑。

编辑规则时，你省略的任何内容都保持不变。要清除某个值，传入 [] 或 ""。Monarch 在每次编辑时替换整条规则，因此服务会返回包含你更改的完整规则。这样可以保留工具无法编辑的设置，例如归属、目标和分拆。

apply_to_existing_transactions=True 还会更改匹配的历史交易。这很难撤销，所以先用 search_transactions 检查匹配项。

概览和支出分析默认使用精简摘要；verbose=True 会恢复完整部分。交易样本分别上限为 500 和 2,000，即使在 verbose 模式下也是如此。在将总数视为完整之前，检查 batch_metadata.transactions_truncated；null 表示上游计数不可用。

定期交易

get_recurring_transactions(start_date, end_date) 返回的是预测，而非已入账的历史记录。 日期接受 ISO 格式或自然语言。不提供日期则选择本月；提供一个日期时， 缺失的边界将从该日期所在月份补齐。

返回的 occurrence 包含 stream、账户、分类，以及在可用时匹配的 transactionId。 isPast 并不意味着已支付。使用 get_transactions(is_recurring=True) 获取已记录的交易；不要将预测和已入账的匹配项重复计算。

update_recurring_transaction 更改的是商户级别的计划，而非单个 occurrence。 使用 stream.merchant.id，而非 stream.id 或 transactionId，并传入当前商户 名称以避免重命名。只传入需要更改的设置：frequency、base_date、 amount、is_recurring 或 is_active。省略的设置保持不变。 使用 Monarch 的频率和有符号金额。这不会取消订阅、 转移资金或创建已入账交易。

交易格式

get_transactions 和 search_transactions 默认返回精简记录：

{
  "id": "txn_123",
  "date": "2025-03-15",
  "amount": -12.50,
  "merchant": "Corner Deli",
  "plaidName": "CORNER DELI NYC",
  "category": "Restaurants & Bars",
  "categoryId": "cat_001",
  "account": "Main Credit Card",
  "needsReview": true
}

pending 仅在为 true 时出现；notes 仅在非空时出现。在 get_transactions 或 search_transactions 上设置 verbose=True 可获取完整交易详情，或在 get_transaction_categories 上设置以获取完整分类详情。

会话管理

会话会缓存于 ~/.monarch-mcp/ 中，以便后续登录更快（可通过 MONARCH_SESSION_DIR 环境变量覆盖该位置）。如果你遇到认证问题：

• 删除 ~/.monarch-mcp/session.pickle 以清除缓存的会话
• 在你的环境配置中设置 MONARCH_FORCE_LOGIN=true 以强制重新登录
• 确保你的系统时钟准确（TOTP 需要）

开发

本地设置

如需进行实时检查，请创建一个 .env 文件（已被 git 忽略），并使用 uv --env-file 显式加载它：

MONARCH_EMAIL="[email protected]"
MONARCH_PASSWORD="your-password"
MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"

测试

uv run pytest tests/ -v                          # offline; live tests are skipped
MONARCH_RUN_INTEGRATION=true uv run --env-file .env pytest tests/test_integration.py -v
uv run --env-file .env scripts/health_check.py    # live API connectivity check

集成测试共享一次全新登录，以避免 MFA 重用和登录限流。它们从不自行加载 .env，也不读取或写入已保存的会话。

CI 检查

运行与 CI 相同的检查：

uv run python scripts/ci.py

发布

使用 /release 来更新 pyproject.toml、提交、打标签 vX.Y.Z、推送并创建 GitHub release。发布工作流通过 OIDC 发布到 PyPI 和 MCP Registry，并根据标签设置 server.json 的版本。

日志分析

衡量工具调用次数和输出大小：

uv run scripts/analyze_logs.py                    # full report
uv run scripts/analyze_logs.py --json             # JSON output
uv run scripts/eval_session.py snapshot           # mark log position
# ... use tools in Claude ...
uv run scripts/eval_session.py analyze            # analyze new entries

安全

警告： 此服务使用非官方的 Monarch Money API 访问方式。你的凭据会授予完整的账户访问权限，包括写入权限。

• 该服务在本地运行，并将请求的财务数据返回给你的 MCP 客户端。请审查客户端的隐私设置和工具审批。
• 保护好你的密码和 MFA 密钥。TOTP 密钥可支持持续生成验证码。
• ~/.monarch-mcp/ 中的会话文件包含认证令牌。请保护好它们以及任何自定义的 MONARCH_SESSION_DIR。
• 日志可能包含财务输入值和错误详情。分享前请先审查。
• 绝不要提交包含凭据的 .env、.mcp.json 或客户端配置文件。
• Monarch Money 可能随时更改或限制非官方 API 访问。

致谢

Fork 自 colvint/monarch-money-mcp。API 访问使用 bradleyseanf/monarchmoneycommunity，基于 hammem/monarchmoney。源码安装会固定某个 commit；PyPI 安装使用已发布的库。

贡献者：@caseypugh（交易拆分）、@seanperkins（支出摘要分页）、@rajatbhagat（设置文档）、@samyk（交易规则）以及 @prerak-proof（交易详情）。