Assistente Financeiro (MCP Server)

Servidor MCP de exemplo, construído com o SDK mcp (MCPServer), que expõe:

• Tool adiciona(a, b) — soma dois números inteiros.

• Resource memory://despesas_mensais — lê o conteúdo de servers/contas_a_pagar.txt.

• Prompt formatar_dado_cadastral(cpf) — gera um prompt para formatar um CPF no padrão xxx.xxx.xxx-xx.

Pré-requisitos

• Python 3.11 (o .venv deste projeto foi criado com essa versão via pyenv-win).

• Node.js + npx — necessários apenas para mcp dev, que baixa e executa o MCP Inspector via npx. Verifique com:

  node --version
  npx --version

Related MCP server: Expense Tracker MCP Server

Instalação

# 1. Criar o ambiente virtual (se ainda não existir)
python -m venv .venv

# 2. Ativar o ambiente virtual
.venv\Scripts\Activate.ps1

# 3. Instalar as dependências
pip install -r requirements.txt

As dependências foram congeladas com pip freeze a partir de um ambiente compartilhado com outros projetos (Streamlit, OpenAI Agents, pandas, etc.) — nem tudo ali é usado por este servidor. O único pacote realmente necessário para rodar servers/server_test.py é o mcp (com o extra cli, para os comandos mcp dev/mcp run):

pip install "mcp[cli]"

Executando o servidor

Opção 1 — Modo desenvolvimento (MCP Inspector)

Sobe o servidor junto com o MCP Inspector (interface web para testar tools, resources e prompts manualmente):

mcp dev servers/server_test.py

Isso abre o Inspector em http://localhost:6274 (o token de sessão aparece no terminal). Requer Node/npx instalados, conforme os pré-requisitos acima.

Opção 2 — Execução direta (stdio)

Para rodar o servidor "puro", sem o Inspector — modo usado por clientes MCP (Claude Desktop, etc.) que já falam o protocolo via stdio:

mcp run servers/server_test.py

Opção 3 — Registrar no Claude Desktop

mcp install servers/server_test.py

Variáveis de ambiente

Existe um arquivo .env na raiz do projeto. O servidor atual (server_test.py) não lê essas variáveis (não há load_dotenv()), então ele funciona mesmo sem o .env.

⚠️ Atenção: o .env deste repositório contém uma chave real da OpenAI em texto puro. Não faça commit desse arquivo e recomenda-se rotacionar a chave. Se algum código futuro precisar dela, carregue com python-dotenv:

from dotenv import load_dotenv
load_dotenv()

Estrutura do projeto

mcp-server/
├── .env                       # variáveis de ambiente (não versionar)
├── requirements.txt           # dependências (pip freeze do ambiente)
└── servers/
    ├── server_test.py         # servidor MCP (tool, resource, prompt)
    └── contas_a_pagar.txt     # dados lidos pelo resource despesas_mensais

Observações de compatibilidade

• Este projeto usa mcp==2.1.1. Na versão 2.x, FastMCP foi renomeado para MCPServer (from mcp.server.mcpserver import MCPServer) — se for consultar exemplos antigos do SDK (FastMCP), adapte o import.

• O pacote openai-agents==0.0.14 (presente no requirements.txt, mas não usado por este servidor) exige mcp<2. Isso significa que pip install -r requirements.txt falha do zero por conflito de dependências caso ambos sejam instalados juntos. Se você não usa openai-agents neste projeto, pode removê-lo do requirements.txt; caso use, atualize-o para >=0.19 (compatível com mcp<3,>=1.19.0).