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": [...]}，因此即使某家银行出现故障，也不会中断整个查询。

快速入门

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

1. Plaid 设置

1. 在 https://dashboard.plaid.com/signup 注册 → 选择 Trial（试用）计划（免费，10 个项目）。

2. Team Settings → Products：启用 Transactions、Liabilities、Investments。

3. Team Settings → API：复制您的 client_id 和生产环境 secret。

2. 安装

git clone https://github.com/<you>/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

尝试输入 “list my accounts” 以确认。

部署

对于可以在任何地方使用的部署：

• 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（作者使用的方式 — 零经常性成本）：请参阅 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 令牌脱敏、每个项目 5 分钟的健康缓存、响应格式化、结构化错误映射。

• link_helper.py — 仅限本地的 FastAPI 应用，用于 Plaid Link。如果设置了 HORIZON=1，则拒绝运行。

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

贡献

请参阅 CONTRIBUTING.md。范围刻意保持狭窄：只读、单租户、由 Plaid 支持。