Monarch MCP Server

🚀 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. 安装

1. 克隆仓库：

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

2. 安装依赖：

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

3. 配置 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 替换为你实际的路径！

4. 重启 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 传输

🛠️ 可用工具

💻 使用示例

基础用法

查看账户信息

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

获取近期交易记录

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

检查支出与预算情况

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

分析现金流

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

📅 日期格式

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

🔧 故障排除

认证问题

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

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

会话过期

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

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

常见错误信息

• “未找到有效会话”：运行 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 许可证。

🆘 支持

如果你遇到问题：

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

🔄 更新

要更新服务器：

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