Monarch MCP

Monarch Money MCP 服务

通过 Claude Desktop 与 Monarch Money 个人财务平台集成的模型上下文协议（MCP）服务。

概览

• 安全设计 — 基于浏览器登录，令牌存储在操作系统密钥链中（绝不会存储在配置文件或环境变量中）
• 默认安全 — 只读模式可防止意外更改；写入工具需要明确选择启用
• 功能全面 — 提供 44 种工具，涵盖账户、交易、拆分、预算、现金流、标签、类别、交易规则、定期商户和信用记录
• 易于安装 — 可通过 Claude Desktop 扩展（.mcpb）、uvx 或 pip 安装

两种运行模式：

服务默认以只读模式启动。在明确选择启用之前，写入工具处于隐藏和禁用状态。

	只读模式（默认）	写入模式
查看账户、交易、预算	是	是
分析现金流、支出、净资产	是	是
创建交易、标签、类别、规则	否	是
更新账户、预算、拆分	否	是
删除交易、标签、账户	否	是

快速开始

安装

选项 1：Claude Desktop 扩展（.mcpb）— 推荐用于 Claude Desktop

可直接在 Claude Desktop 应用中切换启用或禁用写入模式。

1. 从 Releases 下载最新的 .mcpb
2. 在 Claude Desktop 中：Settings > Extensions > Advanced Settings > Install Extensions — 选择 .mcpb 文件
3. 重启 Claude Desktop

要启用写入工具：Settings > Extensions > Monarch Money MCP Server > Configure — 切换 "Enable write tools" 并点击 Save。

---

选项 2：uvx（无需安装）— 推荐用于 Agent（例如 Claude Code 或 Cursor）

也适用于 Claude Desktop，但无法在应用中切换写入模式 — 请在配置中设置。

将以下内容添加到 MCP 配置文件：

{
  "mcpServers": {
    "Monarch Money": {
      "command": "uvx",
      "args": ["monarch-mcp"]
    }
  }
}

要启用写入工具：

{
  "mcpServers": {
    "Monarch Money": {
      "command": "uvx",
      "args": ["monarch-mcp", "--enable-write"]
    }
  }
}

---

选项 3：pip install — 推荐用于本地安装和 venv

pip install monarch-mcp

贡献者：有关发布流程、版本方案以及通过 TestPyPI 进行预发布测试的信息，请参阅 docs/releasing.md。

使用 Python 解释器的完整路径将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "Monarch Money": {
      "command": "/path/to/bin/python3",
      "args": ["-m", "monarch_mcp"]
    }
  }
}

要启用写入工具，请在 args 中添加 "--enable-write"。

---

选项 4：克隆并安装 — 推荐用于开发

git clone https://github.com/vargahis/monarch-mcp.git
cd monarch-mcp
pip install -e .

然后使用开发环境中的 Python 解释器将以下内容添加到 MCP 配置中：

{
  "mcpServers": {
    "Monarch Money": {
      "command": "/path/to/bin/python3",
      "args": ["-m", "monarch_mcp"]
    }
  }
}

要启用写入工具，请在 args 中添加 "--enable-write"。

身份验证

首次在没有已保存会话的情况下启动 MCP 服务时，会自动在浏览器中进行身份验证。

1. 启动（或重启）Claude Desktop
2. 服务检测到不存在令牌后，会在浏览器中打开登录页面
3. 输入 Monarch Money 邮箱和密码
4. 如果启用了 MFA，请提供 2FA 验证码
5. 身份验证完成后，令牌会保存到系统密钥环中 — 即可使用

要点：

• 仅在浏览器中输入凭据 — 绝不会通过 Claude Desktop 输入
• 令牌存储在操作系统密钥环中 — 重启后仍然有效，可持续数周或数月
• 会话过期后自动重新验证 — 下次调用工具时会再次触发浏览器登录
• 全面支持 MFA
• 备用方案：在无头环境中，可在终端运行 python login_setup.py

有关身份验证架构的技术详情，请参阅 docs/authentication.md。

使用示例

Show me all my financial accounts

What were my last 50 transactions?

How's my budget looking this month?

Analyze my cashflow for the last 3 months

Create a tag called "Business Expenses" in red

可用工具

工具	描述	模式
身份验证
setup_authentication	获取设置说明	读取
check_auth_status	检查身份验证状态	读取
debug_session_loading	排查密钥环问题	读取
账户
get_accounts	获取所有金融账户	读取
get_account_holdings	获取投资持仓	读取
get_account_history	获取历史余额数据	读取
get_recent_account_balances	获取每日余额	读取
get_account_snapshots_by_type	按账户类型查看净资产	读取
get_aggregate_snapshots	每日汇总净值	读取
get_institutions	获取已连接的金融机构	读取
get_account_type_options	获取有效的账户类型	读取
refresh_accounts	请求刷新账户数据	读取
create_manual_account	创建手动账户	写入
update_account	更新账户设置	写入
delete_account	删除账户	写入
交易
get_transactions	获取交易记录并进行筛选（日期、账户、类别、标签、搜索、需要_审核等）	读取
get_transaction_details	获取完整的交易详情	读取
get_transactions_summary	汇总交易统计数据	读取
get_transaction_splits	获取拆分信息	读取
get_recurring_transactions	获取周期性交易	读取
find_merchant_id_by_name	搜索近期交易，查找商家并返回不重复的 ID	读取
create_transaction	创建新交易	写入
update_transaction	更新现有交易（使用 clear_notes 清除备注，使用 clear_goal 取消关联目标）	写入
delete_transaction	删除交易	写入
update_transaction_splits	创建、修改或删除拆分	写入
update_recurring_merchant	将商家标记为周期性商家或取消标记，更新其频率或金额，或停用该商家——每次调用都必须提供 is_recurring（需要 --enable-write）	写入
标签
get_transaction_tags	获取所有标签	读取
create_transaction_tag	创建新标签	写入
delete_transaction_tag	删除标签	写入
set_transaction_tags	为交易设置标签	写入
类别
get_transaction_categories	获取所有类别	读取
get_transaction_category_groups	获取类别组	读取
create_transaction_category	创建类别	写入
delete_transaction_category	删除类别	写入
规则
get_transaction_rules	列出所有交易规则及其条件、操作和近期应用统计数据	读取
create_transaction_rule	创建具有完整条件和操作（类别、标签、商家、金额、拆分等）的交易规则	写入
update_transaction_rule	按 ID 更新规则；将覆盖项合并到当前规则中（处理 Monarch 的 REPLACE 语义）	写入
delete_transaction_rule	按 ID 删除规则	写入
预算与现金流
get_budgets	获取预算信息	读取
get_cashflow	获取现金流分析	读取
get_cashflow_summary	获取现金流摘要	读取
set_budget_amount	设置类别预算	写入
其他
get_subscription_details	获取订阅状态	读取
get_credit_history	获取信用评分历史	读取

测试

本项目包含两类互为补充的测试：

1. 模拟单元测试（质量门槛） — 快速、离线运行，无需连接 Monarch。这些测试会在 CI 中运行，必须保持通过：

uv run pytest tests/

Monarch 客户端使用了模拟对象，因此这些测试不会访问真实账户。下文的实时端到端测试默认不运行。

2. 实时端到端（e2e）集成测试 — 使用真实 Monarch 账户测试 MCP 工具，验证其能否可靠处理实时 API（恶意输入／边缘输入、服务端错误路径）。这些测试需主动启用，且不会在 CI 中运行：

MONARCH_LIVE_TESTS=1 uv run pytest tests/integration -m integration

前提条件：已保存密钥环令牌（运行一次 python login_setup.py），或在环境中设置 MONARCH_EMAIL／MONARCH_PASSWORD。如果没有这些凭据，测试套件将跳过。测试会创建并删除前缀为 MCP-Test- 的数据，并自动清理（测试套件运行后会扫描并移除任何残留数据）。详情和安全说明请参阅 tests/integration/README.md。

此外，还有一个独立的 Agent 测试技能（.claude/skills/test-monarch-mcp/），用于驱动 AI Agent 验证其是否能正确调用工具，与上述两个 pytest 测试套件不同。

🙏 致谢

基于 @robcerda 的 monarch-mcp-server 分叉，由 vargahis 维护。

基于 monarchmoneycommunity Python 库构建。

感谢：

• @robcerda 提供原始 MCP 服务
• @hammem 提供原始 monarchmoney 库
• @bradleyseanf 提供社区分支

许可证

MIT 许可证