FIN App — MCP Server

MCP server que expõe as operações do FIN (finanças pessoais) para qualquer LLM agent via Model Context Protocol.

O que faz

• 22 tools para operar finanças: criar despesas, receitas, transferências, consultar saldos, faturas, relatórios, gerenciar contas e categorias.
• 1 resource (fin://docs/guia) com o guia completo de regras de negócio — ciclo de fatura, estorno, parcelamento, modelo de dados.
• Descriptions ricas em cada tool: quando usar, quando NÃO usar, regras de negócio, armadilhas.

Pré-requisitos

• Node.js 18+
• Uma instância do FIN rodando (local ou na nuvem)
• Service token configurado no FIN (endpoint /api/genius/*)

Setup (recomendado) — com API Key

Cada usuário gera sua própria chave no app FIN. Zero fricção, nada de tokens compartilhados.

Passo 1: Gerar uma API Key

1. Acesse o app FIN (web ou mobile)
2. Vá em Configurações → Chaves de API
3. Clique em "Nova chave"
4. Dê um nome (ex: "Claude Code", "Personal Genius")
5. Copie a chave gerada (fin_live_xxx) — ela só é mostrada uma vez

Passo 2: Configurar o Claude Code

Um único comando:

claude mcp add fin-app \
  -s user \
  -e FIN_BASE_URL=https://fin-app-wine.vercel.app \
  -e FIN_API_KEY=fin_live_xxx \
  -- npx -y fin-app-mcp

Ou edite manualmente o settings.json do Claude Code:

{
  "mcpServers": {
    "fin-app": {
      "command": "npx",
      "args": ["-y", "fin-app-mcp"],
      "env": {
        "FIN_BASE_URL": "https://fin-app-wine.vercel.app",
        "FIN_API_KEY": "fin_live_xxx"
      }
    }
  }
}

Passo 3: Testar

Reinicie o Claude Code. Rode claude mcp list — o fin-app deve aparecer como conectado. As tools do FIN ficam disponíveis automaticamente.

Variáveis de ambiente

| Variável | Descrição | |----------|-----------| | FIN_BASE_URL | URL base da instância do FIN (ex: https://fin-app-wine.vercel.app) | | FIN_API_KEY | API key pessoal (fin_live_xxx) gerada em /settings/api-keys |

Setup legado — com Service Token (backward-compat)

Modo antigo, ainda suportado. Requer conhecer o FIN_SERVICE_TOKEN (env var do deploy) e o UUID do usuário no Supabase.

{
  "mcpServers": {
    "fin-app": {
      "command": "npx",
      "args": ["-y", "fin-app-mcp"],
      "env": {
        "FIN_BASE_URL": "https://fin-app-wine.vercel.app",
        "FIN_SERVICE_TOKEN": "shared-secret",
        "FIN_USER_ID": "uuid-do-usuario"
      }
    }
  }
}

Variáveis:

| Variável | Descrição | |----------|-----------| | FIN_BASE_URL | URL base da instância do FIN | | FIN_SERVICE_TOKEN | Service token compartilhado | | FIN_USER_ID | UUID do usuário no Supabase |

Se FIN_API_KEY e as variáveis legadas estiverem setadas juntas, FIN_API_KEY tem precedência.

Opções de instalação

Via npx (padrão)

O npx -y fin-app-mcp baixa e executa automaticamente. Updates automáticos na próxima invocação.

Instalação global

npm install -g fin-app-mcp

Depois use "command": "fin-app-mcp" na config (sem npx).

Clone local (desenvolvimento)

git clone https://github.com/pe-menezes/fin-app.git
cd fin-app/mcp-server
npm install

Aponte o command pro index.mjs local.

Resource: Guia do FIN

O server expõe fin://docs/guia — um guia completo para agents operarem o FIN. Conteúdo:

• Modelo de dados (contas, transações, categorias)
• Valores em centavos
• Ciclo de fatura de cartão (reference_month, closing_day, due_day)
• Estorno / Reversal (como criar, armadilhas)
• Parcelamento (geração automática, deleção em grupo)
• Nomes vs IDs

Agents devem ler este resource antes de iniciar operações financeiras.

Desenvolvimento

O server é um proxy da API Genius do FIN — não contém lógica de negócio própria. Quando regras de negócio mudam no FIN, as descriptions e o guia devem ser atualizados aqui.

# Rodar direto (para debug)
FIN_BASE_URL=http://localhost:3000 FIN_SERVICE_TOKEN=xxx FIN_USER_ID=xxx node index.mjs