Firefly III MCP Server

Firefly III MCP Server

Um servidor Model Context Protocol que dá a um assistente de IA acesso à sua própria instância do Firefly III — 152 operações distribuídas em 5 ferramentas com escopo definido, com leitura, escrita e exclusão mantidas como três superfícies separadas e explicitamente autorizadas, em vez de uma única ferramenta que pode fazer as três coisas.

Türkçe: README.tr.md

• "Em que gastei mais no mês passado?"
• "Encontre transações não categorizadas de agosto e sugira categorias."
• "Mostre-me assinaturas cujo valor aumentou."

Cada pessoa executa isso contra sua própria instância do Firefly com seu próprio token — não há backend hospedado ou intermediário no caminho.

Listado no MCP Registry oficial como io.github.YakupEmreYerli/mcp-firefly-iii, no Glama e na documentação de aplicativos de terceiros do próprio Firefly III. Cada versão é compilada e publicada por CI a partir de um commit etiquetado, com proveniência npm atestando que o pacote veio deste repositório.

Demonstração

https://github.com/user-attachments/assets/4866f13e-ff09-43b0-b99c-2b4789a30224

Demonstração de 38 segundos: faça uma pergunta financeira, leia a resposta via MCP, visualize uma alteração com dry_run, aprove-a e grave-a de volta no Firefly III. Gravado contra uma instância sintética — todos os dados financeiros exibidos são fictícios.

Recursos

• 5 meta-ferramentas, não 152. firefly_query, firefly_mutate, firefly_destructive, além de firefly_list_operations e firefly_get_schema para descoberta — um registro tipado mapeia cada endpoint do Firefly para essas ferramentas, em vez de inundar a lista de ferramentas do modelo.
• dry_run em cada escrita, retornando a solicitação exata — IDs de registros resolvidos incluídos — sem enviá-la.
• Escritas em lote não podem ser executadas às cegas. Atualizações orientadas por filtro exigem max_matches e recusam uma varredura incompleta antes da primeira escrita; grupos de transações com múltiplas divisões são rejeitados imediatamente, em vez de arriscar a soma de seus valores.
• Leitura/escrita/destrutivo são separadamente escopados e aplicados, não apenas anotados — via stdio pelo token do Firefly, via HTTP por escopo OAuth ou token estático.
• Servidor de autorização OAuth 2.1 embutido para Claude web, Claude mobile e ChatGPT — sem necessidade de instalação separada de Keycloak ou Authentik.
• Imagens Docker para linux/amd64/linux/arm64 e um pipeline de documentação com autoverificação que mantém o catálogo de ferramentas sincronizado com o código.
• Ele avisa quando está desatualizado. Uma vez por dia, verifica se existe uma versão mais recente e, se existir, informa uma vez — uma linha no stderr, uma frase ao lado da próxima resposta. MCP_UPDATE_CHECK=false desativa isso.

Pré-requisitos

• Uma instância do Firefly III em execução e um Personal Access Token (Firefly III → Opções → Perfil → OAuth → Criar Novo Personal Access Token)
• Node.js 20.6+, a menos que você use Docker

Uso

Método	Transporte	Melhor para
npx — stdio	stdio	Claude Code, Claude Desktop, Cursor — configuração mais simples
Token estático	HTTP	n8n, automação, chamadas headless
OAuth	HTTP + OAuth	Claude web, Claude mobile, ChatGPT — não podem armazenar token estático
Docker	HTTP	Autohospedado, em qualquer um dos modos de autenticação acima

1. stdio (Claude Code, Claude Desktop, Cursor)

Deixe a configuração fazer o trabalho — ela pergunta o endereço e o token do seu Firefly III, verifica se realmente funcionam e então configura o Claude Code e o Claude Desktop se os encontrar: npx -y @yakupemreyerli/firefly-mcp setup. Para qualquer outro cliente, ela imprime a configuração para colar.

Manualmente, no Claude Code:

claude mcp add firefly --env FIREFLY_API_URL=your-firefly.example --env FIREFLY_API_TOKEN=your-token -- npx -y @yakupemreyerli/firefly-mcp

Manualmente, no Claude Desktop / Cursor / outros clientes — adicione ao arquivo de configuração MCP:

{
  "mcpServers": {
    "firefly": {
      "command": "npx",
      "args": ["-y", "@yakupemreyerli/firefly-mcp"],
      "env": { "FIREFLY_API_URL": "your-firefly.example", "FIREFLY_API_TOKEN": "your-token" }
    }
  }
}

2. HTTP remoto com token estático

Para n8n, automação ou qualquer chamador que não possa conduzir um fluxo OAuth baseado em navegador. Defina MCP_HTTP_TOKEN em .env e execute npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http. Cada solicitação para /mcp deve conter Authorization: Bearer <token> — um token, acesso total, sem escopo por conexão.

3. HTTP remoto com OAuth (Claude web, Claude mobile, ChatGPT)

Nenhum desses clientes pode armazenar um token estático, e nenhum deles pode iniciar um processo local — eles se conectam a uma URL HTTPS pública e esperam OAuth. Com MCP_AUTH_PASSWORD definido, este servidor é o servidor de autorização OAuth 2.1: ele lida com registro de cliente, PKCE e troca de token por conta própria, então não há Keycloak, nem login do Google e nenhum token para copiar em lugar algum.

Etapa 1 — dê ao servidor um endereço HTTPS público. O Cloudflare Tunnel é o caminho mais fácil para um servidor doméstico (sem redirecionamento de porta, sem certificado); Caddy ou Traefik funcionam em um VPS. compose.example.yml inclui perfis cloudflare e caddy exatamente para isso. Digamos que o resultado seja https://mcp.example.com.

Etapa 2 — configure .env:

MCP_AUTH_PASSWORD=a-strong-password-of-at-least-12-characters
MCP_RESOURCE_URL=https://mcp.example.com
MCP_AUTH_STATE_DIR=/data/firefly-mcp-auth

MCP_RESOURCE_URL é a origem externa, caractere por caractere, sem caminho — não o http://firefly-mcp:3000 interno, nem a URL de conexão /mcp. Uma incompatibilidade falha na verificação de público do token e o cliente apenas relata "token inválido". MCP_AUTH_STATE_DIR deve estar em um volume persistente (compose.example.yml monta um) ou cada reinicialização desautoriza todos os clientes.

Etapa 3 — inicie e verifique:

docker compose -f compose.example.yml up -d
curl https://mcp.example.com/health     # {"ok":true,"auth":"oauth-builtin"}

Se auth disser bearer em vez disso, a senha nunca chegou ao processo e o cliente relatará que o servidor não suporta OAuth.

Etapa 4a — Claude (web, Desktop, iOS/Android). Configurações → Conectores → Adicionar conector personalizado, URL https://mcp.example.com/mcp. Deixe as opções de autenticação como detectadas — o Claude testa o servidor e escolhe o fluxo que suporta. O conector então funciona em todas as superfícies do Claude em que você está conectado, incluindo o celular.

Etapa 4b — ChatGPT. Na tela de conector personalizado / MCP, insira o mesmo https://mcp.example.com/mcp e escolha OAuth como método de autenticação.

Etapa 5 — insira a senha. Uma tela de login do Firefly abre no navegador; digite MCP_AUTH_PASSWORD. Essa única tela é toda a decisão — a conexão recebe todos os três escopos (firefly:read, firefly:write, firefly:destructive), independentemente do que o próprio cliente solicitou. Não há segunda tela de consentimento: quem possui a senha poderia ter marcado todas as caixas nela. Para fornecer uma conexão que genuinamente não pode escrever, dê ao servidor um Personal Access Token do Firefly somente leitura.

Receitas completas de TLS e solução de problemas: docs/oauth.md.

4. Docker

Recomendado para qualquer um dos modos HTTP acima:

cp .env.example .env    # fill in the values for the mode you need
docker compose -f compose.example.yml up -d

Troque build: . em compose.example.yml por image: ghcr.io/yakupemreyerli/mcp-firefly-iii:latest para usar a imagem pré-compilada — fixe uma tag de versão, não :latest, para qualquer coisa da qual você dependa. Contêiner único sem Compose: docker run -d --env-file .env -p 3000:3000 ghcr.io/yakupemreyerli/mcp-firefly-iii:latest. Ele se recusa a iniciar sem um dos dois modos de autenticação acima, e /mcp precisa de TLS na frente — compose.example.yml tem perfis opcionais cloudflare e caddy para isso. /health está aberto, para sondagens de contêiner.

Configuração

Variável	Padrão	Finalidade
FIREFLY_API_URL	—	Obrigatório. Um domínio simples ou uma URL base completa incluindo /api/v1.
FIREFLY_API_TOKEN	—	Obrigatório. Personal Access Token.
FIREFLY_DISABLE_SSL_VERIFY	false	Apenas para uma instância local com certificado autoassinado.
MCP_UPDATE_CHECK	true	Verificação diária de uma versão mais recente. A única solicitação que este servidor faz a qualquer lugar além da sua instância do Firefly, e ela não carrega dados.

Cada variável, incluindo modos HTTP e OAuth: docs/configuration.md.

Ferramentas

Ferramenta	Responde	Risco
firefly_query	Leia qualquer coisa. Sua descrição carrega o catálogo, então escolher uma operação não custa chamada extra.	somente leitura
firefly_mutate	Crie ou altere um registro.	escritas
firefly_destructive	Exclua um registro ou reescreva um campo em muitos registros de uma vez.	não pode ser desfeito
firefly_list_operations	O que posso fazer com esta entidade?	somente leitura
firefly_get_schema	Quais parâmetros esta operação aceita?	somente leitura

A divisão é aplicada, não apenas anunciada — uma exclusão alcançada via firefly_query é recusada, e uma conexão concedida apenas com firefly:read nunca vê as duas ferramentas de escrita. As respostas são reduzidas antes de chegarem ao modelo: atributos vazios e nulos são sempre removidos, e cada ferramenta de execução aceita uma lista fields — aproximadamente 90% de redução em uma lista grande de transações. Referência completa: docs/api/operations.md.

Segurança

Este servidor nunca envia seus dados a terceiros, mas não controla o que o cliente de IA ou o modelo ao qual você o conecta faz com uma resposta depois que a recebe. Modelo de ameaça completo: SECURITY.md. Encontrou uma vulnerabilidade? Reporte-a em privado lá.

Documentação

Página	O que cobre
Quickstart	Obter um token, conectar seu cliente, primeiras coisas para tentar, solução de problemas
Configuração	Cada variável de ambiente, a política de permissões, modo HTTP
Acesso remoto com OAuth embutido	Implantação para Claude web, Claude mobile e ChatGPT
Integração MCP	Claude Code, Claude Desktop, Cursor, VS Code, n8n e HTTP remoto
Operações	Todas as 152 operações, redução de respostas, as peculiaridades do Firefly que causam problemas
Operações de Análise	summary.overview, pesquisa e os oito endpoints de insights
MCP Inspector	Explorar o servidor interativamente durante o desenvolvimento

Desenvolvimento

git clone https://github.com/YakupEmreYerli/mcp-firefly-iii.git && cd mcp-firefly-iii
npm install
cp .env.example .env    # fill in your instance
npm test                # mocked; never touches a live instance
npm run build
npm run check           # read-only connection check against .env

Os testes são simulados e nunca alcançam a rede. npm run smoke:live é uma ferramenta de manutenção que percorre cada operação de leitura contra a instância em .env; é somente leitura e não faz parte do pacote publicado. Relatórios de bugs e pull requests são bem-vindos — veja CONTRIBUTING.md.

Licença

MIT — veja LICENSE.