Firefly III MCP Server
daften/fireflyiii-mcp
Integre seu assistente de IA ao Firefly III para gerenciar finanças por conversa
Ver no GitHubServidor MCP que conecta assistentes de IA compatíveis ao Firefly III, sua instância de finanças pessoais. Oferece 140 ferramentas para consultar gastos, gerenciar orçamentos, detectar transações duplicadas e criar metas de economia em linguagem natural.
Instalação
npx convez-ai daften/fireflyiii-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Consultar gastos por categoria em linguagem natural
- Monitorar status de orçamentos mensais
- Detectar transações duplicadas automaticamente
- Criar e gerenciar cofrinhos (piggy banks) para metas de economia
- Analisar padrões de gasto ao longo do tempo
Veredito

Integração sólida e bem documentada que transforma o Firefly III em um assistente financeiro conversacional. Suporta múltiplos métodos de deploy (stdio, HTTP, Docker) com autenticação flexível.
README
A tradução para o português deste README ainda está na fila.
MCP server for Firefly III
An MCP (Model Context Protocol) server that connects any MCP-compatible AI assistant to your Firefly III personal finance instance. Ask your AI assistant questions about your finances in natural language.
📖 Full documentation → daften.github.io/fireflyiii-mcp
What you can ask
Once configured, you can ask things like:
- "How much did I spend on groceries last month?"
- "Show me my budget status for this month."
- "Find any duplicate transactions in the last 30 days."
- "Set up a piggy bank for my vacation fund with a €2000 target."
- "What were my biggest expense categories this year?"
Your AI assistant handles the Firefly III API calls — you get answers in plain language.
Choose your setup method:
| Method | Transport | Best for |
|---|---|---|
| npm — stdio | stdio | Simplest setup, AI on the same machine |
| npm — HTTP | HTTP + OAuth | Remote AI access or when you prefer OAuth over a PAT |
| Docker — HTTP | HTTP + OAuth | Self-hosted on a server or home lab |
| Git checkout | stdio or HTTP | Contributing or local development |
All options except Docker require Node.js 20+.
Option 1: npm package — stdio (simplest)
Requires: Node.js 20+, a Firefly III Personal Access Token (Options → Remote access and tokens → Create new token).
Add to your Claude MCP config (.claude/mcp.json or Claude Desktop claude_desktop_config.json):
{
"mcpServers": {
"fireflyiii": {
"command": "npx",
"args": ["-y", "@daften/fireflyiii-mcp"],
"env": {
"FIREFLY_URL": "https://your-firefly-instance.example.com",
"FIREFLY_TOKEN": "your-personal-access-token-here"
}
}
}
}
Your MCP client downloads and starts the server automatically on first use. No separate install step needed.
Option 2: npm package — HTTP (OAuth)
→ See HTTP/OAuth setup guide in the docs.
Option 3: Docker — HTTP (self-hosted)
→ See Docker setup guide in the docs.
Option 4: Git checkout (development)
→ See Git checkout guide in the docs.
Experimental Autocomplete Prompts
→ See Autocomplete prompts in the docs.
Available Tools
→ See the full tool reference in the docs (140 tools across 14 groups).
Filtering Tools
→ See Tool filtering in the docs.
Development
npm test # Run unit tests
npm run test:watch # Watch mode
npm run test:integration # Run against live Firefly III (requires FIREFLY_URL + FIREFLY_TOKEN)
npm run dev # Run without building (uses tsx)
npm run build # Compile TypeScript to dist/
Resources
- Firefly III API Documentation — interactive Swagger UI for all API versions
- Firefly III OpenAPI YAML — machine-readable spec; fetch with
curl -s "https://api-docs.firefly-iii.org/firefly-iii-6.5.5-v1.yaml" -A "Mozilla/5.0"(direct browser access blocked by bot protection) - Firefly III Docs
- MCP Documentation
Contributing
See CONTRIBUTING.md for the development loop, tool-add checklist, and commit conventions.
Security
See SECURITY.md for the vulnerability disclosure policy.
Acknowledgements
Feature comparison informed by fabianonetto/mcp-server-firefly-iii and etnperlong/firefly-iii-mcp.
License
MIT