Personal Finance MCP Server

Um servidor MCP que pode ser integrado ao seu sistema Claude para orientá-lo a calcular melhor as finanças pessoais no ecossistema Claude.

GitHub

Experimente este MCPPatrocinado

Documentação

💰 Personal Finance MCP

Kit de finanças pessoais determinístico exposto sobre o Model Context Protocol — 77 calculadoras, um meta-assessor e dados de mercado ao vivo, com uma interface web refinada. Fundamentado em matemática financeira consolidada.

Demonstração ao vivo: https://sarveshtalele-personal-finance-mcp.hf.space URL do conector: https://sarveshtalele-personal-finance-mcp.hf.space/mcp

Demonstração

▶️ Assista à demonstração de 2 minutos — pergunta em linguagem natural → ferramentas encadeadas → um plano priorizado.

Nota sobre a demonstração pública: o Space hospedado é uma instância compartilhada de melhor esforço (com limite de taxa, pode demorar para iniciar após ficar ocioso). Para uso intenso ou privado, execute localmente ou faça auto-hospedagem (veja docs/HOW_IT_WORKS.md).

Visão geral

A maioria dos "assistentes" financeiros adivinha números. Este não. Ele traz 77 calculadoras determinísticas — mesmas entradas, mesma resposta, sempre — e permite que um LLM direcione uma pergunta em linguagem natural para as ferramentas certas. Descreva sua situação ("Tenho 30 anos, ganho ₹1L/mês, quero me aposentar aos 60") e o orquestrador create_financial_plan encadeia as calculadoras relevantes em um único plano priorizado.

Ele funciona de três maneiras a partir de um único código-base:

Como servidor MCP — conecte-o ao Claude Desktop, Claude Code, Cursor ou qualquer cliente MCP.
Como site — uma interface Next.js com calculadora ao vivo, painel de mercado e catálogo de ferramentas.
Como conector hospedado — implantado em um Hugging Face Docker Space; uma única URL faz tudo.

Destaques

🔢 Determinístico — matemática pura, sem inferência de modelo para os números.
🤖 História → ferramentas — o modelo mapeia a intenção para ferramentas; os usuários nunca as nomeiam.
🇮🇳 Fundamentado em teoria — TVM, dívidas, PPF/SSY/NSC/EPF, títulos, derivativos, MPT e mais.
🛰️ Dados de mercado ao vivo — NAVs de fundos mútuos (AMFI), câmbio (ECB), cotações de ações (Yahoo) — sem chaves de API.
🔒 Endurecido — APIs sem estado, com limite de taxa, entradas limitadas e cabeçalhos de segurança/CSP.

Catálogo de ferramentas — 77 ferramentas, 13 categorias

Categoria	Ferramentas	Exemplos
Valor do Dinheiro no Tempo	10	valor futuro/presente, anuidade, perpetuidade, TEA, retorno real
Análise de Portfólio	11	CAPM, Sharpe, Sortino, Treynor, alfa, alocação, rebalanceamento
Planejamento Financeiro	9	patrimônio líquido, índices, fundo de emergência, aposentadoria, educação, seguro
Pequenas Poupanças (Índia)	9	PPF, SSY, NSC, KVP, SCSS, RD, FD, EPF
Fundos Mútuos	7	SIP, SWP, valor único vs. SIP, CAGR, NAV, impacto da taxa de despesas
Dívidas e Empréstimos	6	EMI, amortização, pagamento antecipado, consolidação, investir vs. antecipar
Renda Fixa	6	preço do título, YTM, rendimento atual, duração, convexidade, cupom zero
Derivativos	5	valor justo de futuros, payoff de opções, paridade put-call, Black-Scholes, hedge beta
Avaliação de Ações	5	DDM, DDM em dois estágios, P/L, FCD, rendimento de dividendos
Dados de Mercado ao Vivo	4	busca de fundos, NAV ao vivo, taxa de câmbio, cotação de ação/índice
Fluxo de Caixa e Orçamento	3	fluxo de caixa familiar, dívida sobre renda, fundo de contingência
Perfil de Risco	1	pontuação de adequação → divisão sugerida entre ações/dívida
Assessor	1	`create_financial_plan` — o orquestrador história → plano

Explore todos (com descrições ao vivo) em /tools.

Início rápido

Use o conector hospedado (sem instalação)

Claude Desktop — Configurações → Conectores → Adicionar conector personalizado → cole:

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 — adicione ao mcp.json:

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

Instale a partir do PyPI (servidor stdio)

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

Em seguida, aponte o Claude Desktop para ele:

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

Execute localmente a partir do código-fonte

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, aponte o Claude Desktop para o processo local:

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

O site

python -m src.web serve tudo em uma única porta:

Caminho	O quê
`/`	Site Next.js — página inicial, catálogo de ferramentas, calculadora ao vivo, painel de mercado, guia de configuração
`/mcp`	Servidor MCP via streamable-HTTP — a URL do conector
`/api/*`	Endpoints JSON (catálogo de ferramentas, calculadoras, dados de mercado ao vivo)

Arquitetura

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 arquivo de ferramenta mantém funções puras determinísticas separadas dos wrappers finos @mcp.tool, de modo que as mesmas funções alimentam o servidor MCP, as calculadoras web e os testes.

Segurança

Sem estado — sem banco de dados, sem sessões; cada chamada é independente e reproduzível.
API endurecida — limite de taxa por IP, teto no corpo da requisição e validação de entrada que limita parâmetros que dirigem loops (anos/meses/idade) para prevenir negação de serviço.
Cabeçalhos de segurança — CSP (com frame-ancestors para o embed do Hugging Face), X-Content-Type-Options, Referrer-Policy, Permissions-Policy; CORS limitado a GET/POST sem credenciais. O middleware de cabeçalhos é implementado na camada ASGI para nunca armazenar em buffer as respostas de streaming /mcp (SSE).
Sem segredos no aplicativo — as fontes de dados ao vivo são públicas e sem chaves.

Veja SECURITY.md para reportar uma vulnerabilidade.

Desenvolvimento

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

Implantação

Implantado como um Hugging Face Docker Space, sincronizado automaticamente do GitHub a cada push para main (veja .github/workflows/hf-sync.yml). Instruções completas — local, Docker e Hugging Face — estão em docs/deployment.md.

Documentação

docs/HOW_IT_WORKS.md — conceitos (MCP, transportes, roteamento semântico), arquitetura completa com diagramas, fluxos de requisição de ponta a ponta, o modelo de segurança, hospedando você mesmo / em um site de portfólio e um roteiro de nível de produção.
docs/deployment.md — implantação local, Docker e Hugging Face.
docs/Architecture.md · docs/testing.md · docs/setup.md

Contribuindo

Contribuições são bem-vindas — veja CONTRIBUTING.md e o Código de Conduta. Boas primeiras issues: adicionar uma calculadora (uma função pura + um wrapper register + um teste), melhorar descrições para um melhor roteamento de ferramentas ou estender a interface web.

Aviso legal

Ferramenta educacional para ilustrar fórmulas financeiras padrão. Não é aconselhamento de investimento. Os valores são ilustrativos; verifique antes de tomar decisões financeiras.

Licença

MIT — livre para usar, modificar e distribuir.