金大哥 - monarch-mcp-server MCP 详情

article

README

🚀 Monarch Money MCP 服务器

这是一款用于与 Monarch Money 个人理财平台集成的模型上下文协议（MCP）服务器。借助该服务器，你可以通过 Claude Desktop 无缝访问自己的金融账户、交易记录、预算信息以及进行财务分析。

我的 MonarchMoney 推荐链接：https://www.monarchmoney.com/referral/ufmn0r83yf?r_source=share

基于 @hammem 开发的 MonarchMoney Python 库构建 —— 这是一个出色的非官方 Monarch Money API，全面支持多因素认证（MFA）。

🚀 快速开始

1. 安装

克隆仓库：

git clone https://github.com/robcerda/monarch-mcp-server.git
cd monarch-mcp-server

安装依赖：

pip install -r requirements.txt
pip install -e .

配置 Claude Desktop：将以下内容添加到你的 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "Monarch Money": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/your/monarch-mcp-server",
        "mcp",
        "run",
        "/path/to/your/monarch-mcp-server/src/monarch_mcp_server/server.py"
      ]
    }
  }
}

重要提示：请将 /path/to/your/monarch-mcp-server 替换为你实际的路径！

重启 Claude Desktop

2. 一次性身份验证设置

重要提示：为确保安全并支持多因素认证（MFA），身份验证将在 Claude Desktop 外部完成。

打开终端并运行以下命令：

cd /path/to/your/monarch-mcp-server
python login_setup.py

按照提示操作：

输入你的 Monarch Money 电子邮件和密码
如果你启用了 MFA，请提供 2FA 代码
会话将自动保存

3. 在 Claude Desktop 中开始使用

完成身份验证后，你可以直接在 Claude Desktop 中使用以下工具：

get_accounts —— 查看所有金融账户
get_transactions —— 查看近期交易记录，并可进行筛选
get_budgets —— 获取预算信息和支出情况
get_cashflow —— 进行收支分析

✨ 主要特性

📊 账户管理

获取账户信息：查看所有已关联金融账户的余额和机构信息
获取账户持仓：查看投资账户中的证券和投资情况
刷新账户信息：请求从金融机构获取实时数据更新

💰 交易访问

获取交易记录：可按日期、账户进行筛选，并支持分页，获取交易数据
创建交易记录：向账户中添加新的交易记录
更新交易记录：修改现有交易记录（金额、描述、类别、日期）

📈 财务分析

获取预算信息：访问预算信息，包括已花费金额和剩余余额
获取现金流信息：分析指定日期范围内的财务现金流，并进行收支明细分析

🔐 安全认证

一次性设置：只需进行一次身份验证，即可在数周或数月内使用
支持 MFA：全面支持双因素认证
会话持久化：无需频繁重新认证
安全可靠：凭证不会通过 Claude Desktop 传输

🛠️ 可用工具

| 工具 | 描述 | 参数 | |------|-------------|------------| | setup_authentication | 获取设置说明 | 无 | | check_auth_status | 检查认证状态 | 无 | | get_accounts | 获取所有金融账户 | 无 | | get_transactions | 获取经过筛选的交易记录 | limit、offset、start_date、end_date、account_id | | get_budgets | 获取预算信息 | 无 | | get_cashflow | 获取现金流分析 | start_date、end_date | | get_account_holdings | 获取投资持仓 | account_id | | create_transaction | 创建新的交易记录 | account_id、amount、description、date、category_id、merchant_name | | update_transaction | 更新现有交易记录 | transaction_id、amount、description、category_id、date | | refresh_accounts | 请求更新账户数据 | 无 |

💻 使用示例

基础用法

查看账户信息

使用 get_accounts 查看我所有的金融账户

获取近期交易记录

使用 get_transactions 并设置 limit 为 50，查看我最近的 50 条交易记录

检查支出与预算情况

使用 get_budgets 查看我当前的预算状态

分析现金流

使用 get_cashflow 分析我最近 3 个月的现金流

📅 日期格式

所有日期应采用 YYYY-MM-DD 格式（例如："2024-01-15"）
交易金额：收入为正数，支出为负数

🔧 故障排除

认证问题

如果你遇到 “需要认证” 的错误：

运行设置命令：cd /path/to/your/monarch-mcp-server && python login_setup.py
重启 Claude Desktop
尝试使用 get_accounts 等工具

会话过期

会话有效期为数周，但如果过期：

再次运行相同的设置命令
输入你的凭证和 2FA 代码
会话将自动刷新

常见错误信息

“未找到有效会话”：运行 login_setup.py
“账户 ID 无效”：使用 get_accounts 查看有效账户 ID
“日期格式错误”：日期请使用 YYYY-MM-DD 格式

🏗️ 技术细节

项目结构

monarch-mcp-server/
├── src/monarch_mcp_server/
│   ├── __init__.py
│   └── server.py          # 主服务器实现文件
├── login_setup.py         # 身份验证设置脚本
├── pyproject.toml         # 项目配置文件
├── requirements.txt       # 依赖文件
└── README.md             # 本说明文档

会话管理

会话将安全存储在 .mm/mm_session.pickle 中
支持自动发现和加载会话
会话在 Claude Desktop 重启后仍然有效
无需频繁重新认证

安全特性

凭证不会通过 Claude Desktop 传输
全面支持 MFA/2FA
会话文件已加密
身份验证在安全的终端环境中处理

🙏 致谢

此 MCP 服务器基于 @hammem 创建的优秀 MonarchMoney Python 库构建。他们的库为本次集成提供了坚实的基础，具体包括：

支持 MFA 的安全认证
全面覆盖 Monarch Money 的 API
会话管理和持久化
文档完善且维护良好的代码库

感谢 @hammem 创建并维护这个重要的库！

📄 许可证

本项目采用 MIT 许可证。

🆘 支持

如果你遇到问题：

使用 check_auth_status 检查认证状态
再次运行设置命令：cd /path/to/your/monarch-mcp-server && python login_setup.py
查看错误日志以获取详细信息
确保 Monarch Money 服务可正常访问

🔄 更新

要更新服务器：

从仓库拉取最新更改
重启 Claude Desktop
如有需要，重新运行身份验证：python login_setup.py

monarch-mcp-server