personal-finance-mcp

No oficial. Este proyecto no está afiliado, respaldado ni patrocinado por Plaid Inc. "Plaid" es una marca comercial de Plaid Inc. Este es un cliente autohospedado que se comunica con la API de Plaid utilizando las credenciales que usted proporcione.

Un servidor MCP de solo lectura y autohospedado que conecta sus bancos, tarjetas de crédito, préstamos y cuentas de corretaje (a través de Plaid) a un cliente MCP como Claude Code. Haga preguntas sobre sus propias finanzas en inglés sencillo, sin intermediarios de terceros (Monarch, Mint, etc.).

Qué puede preguntar

• "¿Cuál es mi saldo total en todas las cuentas?"

• "Muéstrame las transacciones de más de $100 en los últimos 30 días."

• "¿Qué suscripciones sigo pagando?"

• "¿Cuánto gasté en comestibles el mes pasado?"

• "¿Algún banco necesita reautenticación?"

Ejemplo de sesión (ilustrativo):

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), ...

Herramientas

Las 9 herramientas son de solo lectura. Cada una devuelve {<data>: [...], "warnings": [...]} para que un banco con problemas no interrumpa toda la consulta.

Inicio rápido

Requiere Python 3.11+, una cuenta de Plaid (plan de prueba gratuito) y un cliente MCP.

1. Configuración de Plaid

1. Regístrese en https://dashboard.plaid.com/signup → elija el plan Trial (gratuito, 10 elementos).

2. Team Settings → Products: habilite Transactions, Liabilities, Investments.

3. Team Settings → API: copie su client_id y su secret de producción.

2. Instalación

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. Vincular cada banco

Ejecute una vez por cada banco que desee conectar:

uvicorn link_helper:app --port 8765

Abra http://localhost:8765, haga clic en Link a bank y complete Plaid Link. La terminal imprimirá una línea como PLAID_TOKEN_CHASE=access-prod-xxx...: péguela en .env y repita para cada banco.

4. Ejecución

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

5. Añadir a Claude Code

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

Pruebe "list my accounts" para confirmar.

Despliegue

Para un despliegue que pueda usar desde cualquier lugar:

• Docker (incluido): docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcp

• Cualquier host de Python (Fly.io, Railway, Raspberry Pi + Tailscale, un VPS): configure las variables de entorno desde .env.example, exponga /mcp a través de HTTPS y protéjalo con autenticación.

• Prefect Horizon (lo que usa el autor, costo recurrente de $0): consulte docs/DEPLOYMENT.md para ver el tutorial completo.

Proteja el endpoint. Un endpoint MCP expuesto con sus tokens filtra todas las cuentas vinculadas. Use OAuth 2.1, Cloudflare Access o vincúlelo solo a una red privada.

Seguridad

• Inquilino único. Un despliegue por persona. No comparta.

• Solo lectura. Ninguna herramienta modifica el estado en ninguna institución. No añada ninguna que lo haga.

• Los tokens viven en variables de entorno, nunca en el disco. .env está ignorado por git.

• Usted es responsable del cumplimiento de Plaid. Usted es el cliente de Plaid bajo su propia cuenta.

Antes de cada despliegue:

• [ ] .env nunca confirmado: git log --all -- .env no devuelve nada

• [ ] No hay tokens reales en el historial: git log -S'access-prod-' --all solo devuelve marcadores de posición

• [ ] Puerta de autenticación frente al endpoint MCP (o solo localhost)

• [ ] HORIZON=1 (o similar) configurado en el entorno de despliegue, bloqueando link_helper.py allí

• [ ] Compruebe get_institutions_status() cada pocas semanas para ver si hay necesidades de reautenticación

Solución de problemas

La herramienta devuelve vacío a pesar de haber datos reales. Los productos de Plaid no estaban habilitados cuando vinculó el banco. Vuelva a vincular con Transactions + Liabilities + Investments activos. La herramienta muestra PRODUCTS_NOT_SUPPORTED en warnings cuando esta es la causa.

get_institutions_status() muestra re_auth_required. La sesión de Plaid del banco expiró. Ejecute link_helper.py en modo de actualización: su token de acceso existente sigue siendo el mismo. Consulte docs/DEPLOYMENT.md.

Plaid Link muestra un banco como "no compatible" (común con Amex). Por lo general, es un problema de INSTITUTION_REGISTRATION_REQUIRED: los bancos con OAuth necesitan primero el registro por institución en el panel de control de Plaid. Consulte docs/TROUBLESHOOTING.md.

Más problemas: docs/TROUBLESHOOTING.md.

Arquitectura

• server.py — Servidor FastMCP, 9 herramientas de solo lectura.

• plaid_client.py — Envoltorio del SDK de Plaid: redacción de tokens SecretStr, caché de salud de 5 minutos por elemento, formato de respuesta, mapeo de errores estructurado.

• link_helper.py — Aplicación FastAPI solo local para Plaid Link. Se niega a ejecutarse si HORIZON=1 está configurado.

Análisis más profundo (incluyendo por qué /transactions/get sobre /transactions/sync): docs/ARCHITECTURE.md.

Contribución

Consulte CONTRIBUTING.md. El alcance es deliberadamente limitado: solo lectura, inquilino único, respaldado por Plaid.