Personal Finance MCP Server

Un servidor MCP que puede integrarse en tu sistema Claude para guiarte mejor en el cálculo de finanzas personales dentro del ecosistema Claude.

GitHub

Prueba este MCPPatrocinado

Documentación

💰 Personal Finance MCP

Kit de herramientas determinista de finanzas personales expuesto a través del Model Context Protocol — 77 calculadoras, un meta-asesor y datos de mercado en vivo, con una interfaz web pulida. Fundamentado en matemáticas financieras establecidas.

Demo en vivo: https://sarveshtalele-personal-finance-mcp.hf.space URL del conector: https://sarveshtalele-personal-finance-mcp.hf.space/mcp

Demo

▶️ Ver la demo de 2 minutos — pregunta en lenguaje natural → herramientas encadenadas → un plan priorizado.

Nota sobre la demo pública: el Space alojado es una instancia compartida de mejor esfuerzo (con límite de tasa, puede tardar en arrancar tras estar inactivo). Para uso intensivo o privado, ejecútalo localmente o autoalójalo (consulta docs/HOW_IT_WORKS.md).

Resumen

La mayoría de los «asistentes» financieros adivinan los números. Este no. Incluye 77 calculadoras deterministas — mismas entradas, misma respuesta, siempre — y permite que un LLM enrute una pregunta en lenguaje natural hacia las herramientas adecuadas. Describe tu situación («Tengo 30 años, gano ₹1L/mes, quiero jubilarme a los 60») y el orquestador create_financial_plan encadena las calculadoras relevantes en un único plan priorizado.

Se ejecuta de tres maneras desde un mismo código base:

Como servidor MCP — conéctalo a Claude Desktop, Claude Code, Cursor o cualquier cliente MCP.
Como sitio web — una interfaz Next.js con calculadora en vivo, panel de mercado y catálogo de herramientas.
Como conector alojado — desplegado en un Hugging Face Docker Space; una sola URL hace las tres cosas.

Destacados

🔢 Determinista — matemática pura, sin inferencia de modelo para los números.
🤖 Historia → herramientas — el modelo asigna la intención a herramientas; los usuarios nunca las nombran.
🇮🇳 Fundamentado en teoría — TVM, deuda, PPF/SSY/NSC/EPF, bonos, derivados, MPT y más.
🛰️ Datos de mercado en vivo — NAVs de fondos mutuos (AMFI), FX (BCE), cotizaciones de acciones (Yahoo) — sin claves API.
🔒 Endurecido — APIs sin estado, con límite de tasa, entradas acotadas y cabeceras de seguridad/CSP.

Catálogo de herramientas — 77 herramientas, 13 categorías

Categoría	Herramientas	Ejemplos
Valor del dinero en el tiempo	10	valor futuro/presente, anualidad, perpetuidad, TAE, rendimiento real
Análisis de carteras	11	CAPM, Sharpe, Sortino, Treynor, alfa, asignación, rebalanceo
Planificación financiera	9	patrimonio neto, ratios, fondo de emergencia, jubilación, educación, seguros
Pequeños ahorros (India)	9	PPF, SSY, NSC, KVP, SCSS, RD, FD, EPF
Fondos mutuos	7	SIP, SWP, lump-sum vs SIP, CAGR, NAV, impacto del ratio de gastos
Deuda y préstamos	6	EMI, amortización, prepago, consolidación, invertir-vs-prepagar
Renta fija	6	precio de bono, YTM, rendimiento actual, duración, convexidad, cupón cero
Derivados	5	valor razonable de futuros, payoff de opciones, paridad put-call, Black-Scholes, cobertura beta
Valoración de acciones	5	DDM, DDM de dos etapas, P/E, DCF, rendimiento por dividendo
Datos de mercado en vivo	4	búsqueda de fondos, NAV en vivo, tipo de cambio, cotización de acciones/índices
Flujo de caja y presupuesto	3	flujo de caja del hogar, deuda-ingresos, fondo de contingencia
Perfil de riesgo	1	puntuación de idoneidad → división sugerida acciones/deuda
Asesor	1	`create_financial_plan` — el orquestador historia → plan

Explóralas todas (con descripciones en vivo) en /tools.

Inicio rápido

Usar el conector alojado (sin instalación)

Claude Desktop — Ajustes → Conectores → Añadir conector personalizado → pega:

https://sarveshtalele-personal-finance-mcp.hf.space/mcp

Claude Code

claude mcp add --transport http personal-finance https://sarveshtalele-personal-finance-mcp.hf.space/mcp

Cursor / VS Code — añade a mcp.json:

{
  "mcpServers": {
    "personal-finance": {
      "url": "https://sarveshtalele-personal-finance-mcp.hf.space/mcp",
      "transport": "http"
    }
  }
}

Instalar desde PyPI (servidor stdio)

pip install personal-finance-mcp     # or: uvx personal-finance-mcp

Luego apunta Claude Desktop hacia él:

{
  "mcpServers": {
    "personal-finance": { "command": "uvx", "args": ["personal-finance-mcp"] }
  }
}

Ejecutar localmente desde el código fuente

git clone https://github.com/sarveshtalele/personal-finance-mcp.git
cd personal-finance-mcp
pip install -e .

# Option A — classic stdio MCP server (offline, no web)
python -m src

# Option B — unified server: website + /mcp connector + /api  (http://localhost:7860)
cd web && npm install && npm run build && cd ..
python -m src.web

Para stdio, apunta Claude Desktop al proceso local:

{
  "mcpServers": {
    "personal-finance": { "command": "python", "args": ["-m", "src"] }
  }
}

El sitio web

python -m src.web sirve todo en un solo puerto:

Ruta	Qué es
`/`	Sitio Next.js — inicio, catálogo de herramientas, calculadora en vivo, panel de mercado, guía de configuración
`/mcp`	Servidor MCP sobre streamable-HTTP — la URL del conector
`/api/*`	Endpoints JSON (catálogo de herramientas, calculadoras, datos de mercado en vivo)

Arquitectura

src/
├── server.py            # FastMCP server — registers all tool modules
├── __main__.py          # `python -m src`  (stdio transport)
├── tools/               # pure math fns + per-module register(mcp)
│   ├── tvm.py  debt.py  planning.py  bonds.py  stocks.py  mutual_funds.py
│   ├── portfolio.py  derivatives.py  india_savings.py  cashflow.py
│   ├── risk_profile.py  advisor.py   # advisor = story → plan orchestrator
│   └── marketdata.py    # live AMFI / Frankfurter / Yahoo (keyless)
├── models/              # Pydantic schemas + enums
├── utils/               # output formatters
└── web/                 # unified Starlette server (MCP + /api + static site)
    ├── server.py        # routes, security middleware, calculator registry
    └── __main__.py      # `python -m src.web`  (uvicorn, port 7860)

web/                     # Next.js front-end (static export → web/out)
└── app/                 # home, tools, calculator, dashboard, connect

Cada archivo de herramienta mantiene las funciones puras deterministas separadas de los delgados envoltorios @mcp.tool, de modo que las mismas funciones alimentan el servidor MCP, las calculadoras web y las pruebas.

Seguridad

Sin estado — sin base de datos, sin sesiones; cada llamada es independiente y reproducible.
API endurecida — límite de tasa por IP, tope del cuerpo de la solicitud y validación de entrada que acota los parámetros que controlan bucles (años/meses/edad) para prevenir denegación de servicio.
Cabeceras de seguridad — CSP (con frame-ancestors para el embed de Hugging Face), X-Content-Type-Options, Referrer-Policy, Permissions-Policy; CORS limitado a GET/POST sin credenciales. El middleware de cabeceras se implementa en la capa ASGI para que nunca almacene en búfer las respuestas de streaming /mcp (SSE).
Sin secretos en la aplicación — las fuentes de datos en vivo son públicas y sin claves.

Consulta SECURITY.md para reportar una vulnerabilidad.

Desarrollo

pip install -e ".[dev]"
pytest -q                       # 119 tests
ruff check .                    # lint
python -m src.web               # run the full stack locally

Despliegue

Desplegado como un Hugging Face Docker Space, sincronizado automáticamente desde GitHub en cada push a main (consulta .github/workflows/hf-sync.yml). Instrucciones completas — local, Docker y Hugging Face — en docs/deployment.md.

Documentación

docs/HOW_IT_WORKS.md — conceptos (MCP, transportes, enrutamiento semántico), arquitectura completa con diagramas, flujos de solicitud de extremo a extremo, el modelo de seguridad, alojarlo tú mismo / en un sitio de portafolio y una hoja de ruta de nivel producción.
docs/deployment.md — despliegue local, Docker y Hugging Face.
docs/Architecture.md · docs/testing.md · docs/setup.md

Contribuciones

Las contribuciones son bienvenidas — consulta CONTRIBUTING.md y el Código de Conducta. Buenas primeras tareas: añadir una calculadora (una función pura + un envoltorio register + una prueba), mejorar las descripciones para un mejor enrutamiento de herramientas, o ampliar la interfaz web.

Aviso legal

Herramienta educativa para ilustrar fórmulas financieras estándar. No es asesoramiento de inversión. Las cifras son ilustrativas; verifica antes de tomar decisiones financieras.

Licencia

MIT — libre de usar, modificar y distribuir.