Fintable MCP

Servidor MCP não oficial para fintable.io — gerencie categorias financeiras, regras e transações por meio de assistentes de IA em vez de clicar em assistentes de várias etapas.

GitHub

Experimente este MCPPatrocinado

Documentação

fintable-mcp

Um servidor MCP (Model Context Protocol) não oficial para fintable.io, permitindo que assistentes de IA como o Claude gerenciem suas categorias financeiras, regras e transações diretamente — sem precisar navegar por assistentes de várias etapas.

Nota: Este é um projeto da comunidade, não suportado oficialmente pelo fintable.io. Ele funciona comunicando-se com o backend Laravel Livewire 3 do Fintable usando sua sessão do navegador. Se você é o desenvolvedor do Fintable e gostaria de colaborar em um servidor MCP oficial ou API pública, por favor abra uma issue — adoraríamos trabalhar com você! 🤝

O que ele faz

Uma vez instalado, você pode pedir ao Claude ou ao seu cliente MCP favorito coisas como:

"Crie estas categorias de despesas: Material de Escritório, Envio, Embalagem, Aluguel de Equipamentos, Assinaturas de Software"
"Crie regras: 'Staples' → Material de Escritório, 'UPS' → Envio, 'USPS' → Envio"
"Execute todas as regras para categorizar minhas transações"
"Qual é o meu saldo atual da conta no Ally Bank?"
"Liste todas as minhas regras de categorização"

Chega de passar por um assistente de 3 páginas 20 vezes para configurar 20 categorias. Basta dizer ao Claude o que você precisa.

Ferramentas fornecidas

Operações de Leitura

Ferramenta	Descrição
`fintable_list_accounts`	Lista todas as contas bancárias conectadas com saldos
`fintable_list_categories`	Lista todas as categorias de transações
`fintable_list_rules`	Lista regras de categorização (com paginação)
`fintable_list_transactions`	Lista/busca transações com filtros opcionais

Operações de Escrita

Ferramenta	Descrição
`fintable_create_category`	Cria uma única categoria
`fintable_create_bulk_categories`	Cria até 50 categorias de uma vez
`fintable_create_rule`	Cria uma regra de categorização
`fintable_create_bulk_rules`	Cria múltiplas regras de uma vez
`fintable_run_all_rules`	Executa todas as regras em transações não categorizadas
`fintable_delete_rule`	Exclui uma regra de categorização
`fintable_sync_accounts`	Aciona a sincronização de conta bancária via Plaid
`fintable_resync_spreadsheets`	Envia atualizações para Airtable/Google Sheets

Instalação

Pré-requisitos

Python 3.10+
Uma conta no fintable.io com contas bancárias conectadas
Claude Desktop (ou qualquer cliente compatível com MCP — Cherry Studio, etc.)

1. Clone este repositório

git clone https://github.com/jasoncbraatz/fintable-mcp.git
cd fintable-mcp

2. Instale as dependências

pip install -r requirements.txt

Ou com uv (mais rápido):

uv pip install -r requirements.txt

3. Configuração de autenticação

Você tem duas opções — automática (recomendada) ou manual.

Opção A: Extração automática de cookies (recomendada)

Instale o rookiepy, que lê cookies diretamente do banco de dados local do Chrome usando suas credenciais do sistema operacional:

pip install rookiepy

É isso. Contanto que você esteja logado no fintable.io no Chrome, o servidor obtém cookies frescos a cada execução. Sem cópia manual, sem dores de cabeça com expiração.

Opção A½: Jar de cookies auto-atualizável (avançado)

Se você quiser que o servidor mantenha sua própria sessão sem precisar do Chrome ou do rookiepy após a primeira execução, adicione o sinalizador --persist-cookies à sua configuração (veja o passo 4). Isso salva os cookies de sessão em ~/.fintable-mcp-cookies.json e os atualiza automaticamente a partir das respostas do servidor — a sessão permanece ativa enquanto não expirar no lado do servidor entre execuções.

A semente inicial vem de qualquer método de autenticação disponível (rookiepy, variável de ambiente, etc.). Depois disso, o servidor é autossuficiente.

Nota de segurança: Isso armazena cookies de sessão em disco. O arquivo é um dotfile no seu diretório inicial e não é anunciado em lugar nenhum, mas qualquer pessoa com acesso de leitura à sua pasta inicial poderia encontrá-lo. Se isso for uma preocupação, fique com a Opção A.

Nota para Python 3.13+: Você pode precisar definir PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 antes de instalar o rookiepy:
PYO3_USE_ABI3_FORWARD_COMPATIBILITY=1 pip install rookiepy

Opção B: Exportação manual de cookies

Se você preferir não instalar o rookiepy (ou estiver usando um navegador diferente do Chrome):

Abra o Chrome e vá para fintable.io — certifique-se de estar logado
Abra o DevTools (F12 ou Cmd+Option+I)
Vá para a aba Network
Clique em qualquer requisição para fintable.io
Encontre o cabeçalho Cookie em Request Headers
Copie a string completa de cookies

Você passará isso como uma variável de ambiente no próximo passo.

4. Configure o Claude Desktop

Adicione o seguinte ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Se estiver usando rookiepy (Opção A) — nenhuma variável de ambiente necessária:

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"]
    }
  }
}

Se estiver usando --persist-cookies (Opção A½) — combine com rookiepy ou variável de ambiente para a semente inicial:

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py", "--persist-cookies"]
    }
  }
}

Se estiver usando cookies manuais (Opção B):

{
  "mcpServers": {
    "fintable": {
      "command": "python",
      "args": ["/absolute/path/to/fintable-mcp/fintable_mcp.py"],
      "env": {
        "FINTABLE_COOKIES": "your_full_cookie_string_here"
      }
    }
  }
}

💡 Substitua /absolute/path/to/fintable-mcp/fintable_mcp.py pelo caminho real onde você clonou este repositório.

5. Reinicie o Claude Desktop

Após salvar a configuração, saia completamente e reinicie o Claude Desktop. As ferramentas fintable aparecerão na lista de ferramentas do Claude.

Autenticação

Este servidor autentica usando os cookies de sessão do seu navegador fintable.io — os mesmos cookies que seu navegador usa quando você está logado.

Ordem de resolução de cookies:

Jar de cookies persistido — Se --persist-cookies estiver ativo e ~/.fintable-mcp-cookies.json existir com cookies frescos, use-os. Auto-atualiza a partir dos cabeçalhos Set-Cookie do servidor.
rookiepy — Se instalado, os cookies são extraídos frescos do banco de dados local do Chrome a cada início do servidor. Zero manutenção.
Variável de ambiente FINTABLE_COOKIES — String completa de cookies do Chrome DevTools (fallback se o rookiepy não estiver instalado).
Variável de ambiente FINTABLE_SESSION_COOKIE — Apenas o valor do cookie de sessão (opção manual mais simples).

Quando --persist-cookies está ativo, qualquer método que forneça os cookies iniciais também alimentará o jar. Em execuções subsequentes, o jar tem prioridade — e cada resposta do servidor o atualiza automaticamente.

Suas credenciais nunca são armazenadas em disco por este servidor — elas vivem apenas na memória enquanto o servidor está em execução.

Expiração da Sessão

Se você estiver usando rookiepy (recomendado), a expiração da sessão é tratada automaticamente — cookies frescos são obtidos do Chrome a cada início do servidor. Apenas certifique-se de permanecer logado no fintable.io no Chrome.

Se você estiver usando exportação manual de cookies, seus cookies eventualmente expirarão. Quando isso acontecer, o servidor retornará um erro de autenticação. Re-exporte seus cookies do Chrome e atualize a variável de ambiente FINTABLE_COOKIES.

Como funciona (para os curiosos / desenvolvedores)

Fintable.io é uma aplicação Laravel usando Livewire 3 + Alpine.js para seu frontend — não há API REST pública. Este servidor MCP:

Autentica usando os cookies de sessão do seu navegador (token CSRF + cookie de sessão)
Busca páginas para extrair snapshots de componentes Livewire dos atributos HTML wire:snapshot
Faz chamadas de protocolo Livewire — requisições POST para o endpoint /livewire-{hash}/update com snapshots de componentes, chamadas de método e atualizações de propriedades
Analisa respostas HTML para extrair dados estruturados (contas, categorias, regras, transações)

O caminho de atualização do Livewire inclui um hash (ex.: /livewire-5c7ce5a8/update) que pode mudar quando o aplicativo é reimplantado. O servidor descobre automaticamente esse caminho a partir do atributo HTML data-update-uri a cada carregamento de página, então permanece resiliente entre implantações.

Problemas Conhecidos e Limitações

Mudanças no Hash do Livewire

O endpoint de atualização do Livewire inclui um hash de build (ex.: /livewire-5c7ce5a8/update) que muda a cada implantação. O servidor descobre isso automaticamente a cada busca de página, mas se o Fintable reestruturar significativamente seus componentes Livewire ou mudar os nomes dos componentes, as coisas podem quebrar. Isso é inerente ao trabalhar sem uma API oficial.

Fragilidade da Análise HTML

Como não há API JSON, as operações de leitura dependem da análise da estrutura HTML. Se o Fintable redesenhar seu layout de interface, a lógica de análise pode precisar de atualização. Este é o maior fardo de manutenção da abordagem atual.

O Caminho a Seguir: Endpoints JSON

A solução ideal é o Fintable expor endpoints JSON leves. Isso iria:

Eliminar a análise HTML frágil
Remover a dependência do hash do Livewire
Permitir integrações mais confiáveis
Abrir portas para outras ferramentas e integrações da comunidade
Ser um ótimo ponto de venda para o produto (ferramentas financeiras prontas para MCP são um diferencial!)

Se você é o desenvolvedor do Fintable lendo isto — mesmo um punhado de endpoints JSON autenticados para categorias, regras e transações tornaria este servidor extremamente sólido e dramaticamente mais fácil de manter. Feliz em colaborar no design. 🚀

Modelo de Segurança

Este servidor roda localmente na sua máquina como um subprocesso stdio do seu cliente MCP. Ele:

Nunca expõe uma porta de rede
Nunca armazena credenciais em disco
Apenas se comunica com fintable.io usando sua sessão de navegador existente
Roda como um processo de usuário único e cliente único

Por padrão, os cookies de sessão são mantidos apenas em memória enquanto o servidor está em execução. Com o rookiepy, eles são extraídos frescos do Chrome a cada inicialização — sem variáveis de ambiente ou arquivos de configuração necessários.

Se --persist-cookies estiver habilitado, os cookies são salvos em ~/.fintable-mcp-cookies.json (um dotfile no seu diretório inicial). Este é um trade-off opcional: conveniência de uma sessão auto-atualizável em troca de cookies existindo em disco. Exclua o arquivo a qualquer momento para revogar a sessão.

Contribuindo

PRs são bem-vindos! Algumas ideias para melhorias futuras:

Suporte para filtragem por intervalo de datas de transações
Gerenciamento de grupos de categorias (criar/renomear grupos)
Reordenação de prioridade de regras
Exportar categorias/regras como JSON para backup
Suporte para múltiplas contas Fintable

Nota sobre exclusões: A exclusão de categorias não é suportada intencionalmente — essa é uma ação destrutiva melhor feita pela interface web do Fintable, onde você pode ver o impacto completo. Um pouco de fricção antes de excluir coisas é uma funcionalidade, não um bug.

Aviso Legal

Este projeto não é afiliado, endossado ou oficialmente suportado pelo fintable.io. Foi construído por engenharia reversa do protocolo frontend Livewire 3. Use por sua conta e risco — o protocolo Livewire subjacente pode mudar sem aviso.

Licença

MIT - Jason C Braatz