Personal Finance MCP

personal-finance-mcp

非官方。 本项目与 Plaid Inc. 无关联，未经其认可或赞助。“Plaid”是 Plaid Inc. 的商标。这是一个可自托管的客户端，使用你提供的凭据调用 Plaid 的 API。

一个可自托管、只读的 MCP 服务，可将你的银行账户、信用卡、贷款和券商账户（通过 Plaid）连接到 Claude Code 等 MCP 客户端。用通俗的英语询问你自己的财务状况，无需第三方聚合服务（Monarch、Mint 等）。

你可以询问的问题

• “我所有账户的总余额是多少？”
• “显示过去 30 天内金额超过 $100 的交易。”
• “我还在为哪些订阅付费？”
• “我上个月在杂货上花了多少钱？”
• “有哪些银行需要重新进行身份验证？”

会话示例（仅作说明）：

you    : What did I spend on groceries last month?
claude : [calls get_transactions]
         $487.23 across 14 transactions. Top merchants:
         Whole Foods ($198), Trader Joe's ($156), Safeway ($89).

you    : Any subscriptions I'm still paying for?
claude : [calls get_recurring_transactions]
         7 active recurring outflows totaling $142/mo:
         Netflix ($15.99), Spotify ($11.99), NYT ($4), ...

工具

全部 9 个工具均为只读。每个工具都会返回 {<data>: [...], "warnings": [...]}，因此一家银行出问题也不会导致整个查询失败。

工具	功能
list_accounts	列出所有已关联银行的每个账户及其余额
get_balances	获取实时当前余额和可用余额（可选按账户筛选）
get_transactions	获取指定日期范围内的交易（最远可追溯 2 年）
search_transactions	按关键字搜索商户、名称或交易对方
get_recurring_transactions	检测定期收入和支出
get_liabilities	获取信用卡、学生贷款和抵押贷款的 APR 及付款详情
get_investment_holdings	获取当前持仓及其代码和证券元数据
get_investment_transactions	获取指定日期范围内的买入、卖出和股息记录
get_institutions_status	查看每家已关联银行的状态（显示是否需要重新进行身份验证）

快速入门

需要 Python 3.11+、Plaid 账户（免费的 Trial 计划）和 MCP 客户端。

1. 设置 Plaid

1. 在 https://dashboard.plaid.com/signup 注册 → 选择 Trial 计划（免费，10 个 Items）。
2. Team Settings → Products：启用 Transactions、Liabilities、Investments。
3. Team Settings → API：复制你的 client_id 和生产环境 secret。

2. 安装

git clone https://github.com/JosueM1109/personal-finance-mcp.git
cd personal-finance-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then fill in PLAID_CLIENT_ID and PLAID_SECRET
pytest -v              # sanity check

3. 关联每家银行

对要连接的每家银行各运行一次：

uvicorn link_helper:app --port 8765

打开 http://localhost:8765，点击 Link a bank，完成 Plaid Link 流程。终端会输出类似 PLAID_TOKEN_CHASE=access-prod-xxx... 的一行内容——将其粘贴到 .env，并对每家银行重复此步骤。

4. 运行

python server.py   # serves on http://localhost:8000/mcp

5. 添加到 Claude Code

claude mcp add --transport http personal-finance http://localhost:8000/mcp

尝试询问“列出我的账户”以确认配置成功。

部署

如需随时随地使用，可选择以下部署方式：

• Docker（已包含）：docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcp
• 任意 Python 主机（Fly.io、Railway、Raspberry Pi + Tailscale、VPS）：设置 .env.example 中的环境变量，通过 HTTPS 暴露 /mcp，并为其配置身份验证。
• Prefect Horizon（作者使用的方案——每月固定成本为 $0）：完整操作指南见 docs/DEPLOYMENT.md。

保护端点。 暴露的 MCP 端点会泄露你所有已关联账户的令牌。请使用 OAuth 2.1、Cloudflare Access，或仅绑定到专用网络。

安全性

• 单租户。 每人部署一个实例。不要共享。
• 只读。 不会通过任何工具更改任何机构的状态。不要添加会更改状态的工具。
• 令牌仅存于环境变量中，绝不存入磁盘。.env 已加入 gitignore。
• Plaid 合规由你负责。 你是 Plaid 的客户，使用自己的账户。

每次部署前：

• .env 从未提交：git log --all -- .env 无返回结果
• 历史记录中没有真实令牌：git log -S'access-prod-' --all 只返回占位符
• MCP 端点前有身份验证门禁（或仅限 localhost）
• 在部署环境中设置 HORIZON=1（或类似设置），以阻止 link_helper.py 在该环境中运行
• 每隔几周检查一次 get_institutions_status()，确认是否需要重新认证

故障排除

工具返回空结果，但实际存在数据。 链接银行时未启用 Plaid 产品。重新链接，并启用 Transactions、Liabilities 和 Investments。如果这是原因，工具会在 warnings 中显示 PRODUCTS_NOT_SUPPORTED。

get_institutions_status() 显示 re_auth_required。 银行的 Plaid 会话已过期。以更新模式运行 link_helper.py——现有访问令牌保持不变。参见 docs/DEPLOYMENT.md。

Plaid Link 将某家银行显示为“不支持”（Amex 常见）。 通常是 INSTITUTION_REGISTRATION_REQUIRED 问题——OAuth 银行需要先在 Plaid 控制面板中逐一注册。参见 docs/TROUBLESHOOTING.md。

更多问题请参见：docs/TROUBLESHOOTING.md。

架构

• server.py — FastMCP 服务，提供 9 个只读工具。
• plaid_client.py — Plaid SDK 封装：SecretStr 令牌脱敏、每个 Item 的 5 分钟健康状态缓存、响应整形、结构化错误映射。
• link_helper.py — 仅限本地使用的 FastAPI 应用，用于 Plaid Link。设置 HORIZON=1 时拒绝运行。

深入了解（包括为什么使用 /transactions/get 而不是 /transactions/sync）：docs/ARCHITECTURE.md。

贡献

参见 CONTRIBUTING.md。项目范围刻意保持狭窄：只读、单租户、基于 Plaid。