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