Firefly III MCP Server

Dale a un asistente de IA acceso de lectura — y, si se lo permites, de escritura — a tu propia instancia de Firefly III a través del Model Context Protocol.

146 operaciones en 26 entidades: transacciones, cuentas, presupuestos, categorías, etiquetas, facturas, huchas, reglas, además de búsqueda y análisis de períodos.

Türkçe: README.tr.md

Cada cual lo ejecuta contra su propia instancia de Firefly con su propio token. No se comparte nada y ningún dato pasa por un tercero.

Instalación

Requiere Node.js 20.6+. La forma más rápida es dejar que el instalador lo haga:

npx -y @yakupemreyerli/firefly-mcp setup

Pide tu dirección de Firefly III y tu token de API, comprueba que realmente funcionan contra tu instancia y, a continuación, configura Claude Code y Claude Desktop si los encuentra — haciendo una copia de seguridad de todo lo que toca y dejando en paz a tus otros servidores MCP. Para cualquier otro cliente, imprime la configuración que hay que pegar.

Si prefieres hacerlo a mano:

Claude Code

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

Claude Desktop, Cursor y otros clientes

Añade esto al archivo de configuración MCP del cliente:

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

Obtén el token en Firefly III → Opciones → Perfil → OAuth → Crear nuevo token de acceso personal. Para la URL, tu dominio es suficiente — https:// y /api/v1 se rellenan automáticamente. Indica la URL completa si tu instancia está tras una subruta, en un puerto personalizado o en http simple.

Related MCP server: Firefly III MCP Server

Hasta dónde puede llegar

A través de stdio, hasta donde permita el token de Firefly: puedes pedirle al asistente que registre una compra o categorice una transacción y lo hará. No existe un ajuste de permisos global del servidor — para una sesión que solo pueda responder preguntas, emite un token de acceso personal de solo lectura en Firefly III, de modo que el límite lo impone Firefly y no una variable que la misma persona pueda editar.

Sobre HTTP con OAuth, el acceso se decide por conexión: firefly:read, firefly:write y firefly:destructive se conceden en la pantalla de contraseña, y una superficie que no se haya concedido se oculta además de denegarse.

Lo que ve el asistente

Cinco herramientas, no 146 — y la ejecución está dividida por riesgo, de modo que un anfitrión puede distinguir entre leer un saldo y eliminar una transacción:

Cada una lleva anotaciones de herramienta MCP (readOnlyHint, destructiveHint, idempotentHint), y la división se aplica, no solo se anuncia: una eliminación intentada a través de firefly_query se rechaza. Una conexión a la que solo se le haya concedido firefly:read no ve en absoluto las dos herramientas de escritura.

La mayoría de los clientes MCP se degradan a partir de unas 40 herramientas, por eso la superficie es de tres.

Las respuestas se recortan antes de llegar al modelo: los atributos vacíos y nulos se eliminan siempre, y cada herramienta de ejecución acepta una lista fields que conserva solo los atributos que nombres — en una lista grande de transacciones, eso supone un recorte de aproximadamente el 90%.

Configuración

Modo HTTP remoto

Para clientes que se conectan por HTTP en lugar de lanzar un proceso — n8n, por ejemplo — el mismo servidor habla HTTP transmisible:

export MCP_HTTP_TOKEN=$(openssl rand -hex 32)
npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http

firefly-mcp-http es un segundo binario dentro del mismo paquete, por eso npx necesita -p para nombrar el paquete y el comando por separado.

Se niega a arrancar sin MCP_HTTP_TOKEN, y cada petición a /mcp debe llevar Authorization: Bearer <token>. /health está abierto para las sondas de contenedor. En el repositorio hay un Dockerfile y un compose.example.yml.

Ponlo detrás de TLS. El token es lo único que separa Internet del acceso de escritura a tu historial financiero — no expongas el puerto directamente.

Documentación

Docker

Para el modo HTTP hay una imagen precompilada para linux/amd64 y linux/arm64:

docker run -d \
  -e FIREFLY_API_URL=your-firefly.example \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -p 3000:3000 \
  ghcr.io/yakupemreyerli/mcp-firefly-iii:latest

/health responde sin token, para las sondas de contenedor. Todo lo que esté en /mcp necesita Authorization: Bearer <MCP_HTTP_TOKEN>.

Fija una versión (:0.3.1) en lugar de :latest para cualquier cosa de la que dependas.

Desarrollo

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

Las pruebas están simuladas y nunca llegan a la red. npm run smoke:live es una herramienta de mantenimiento que recorre todas las operaciones de lectura contra la instancia en .env; es de solo lectura y no forma parte del paquete publicado.

Contribuciones

Los informes de errores y las pull requests son bienvenidos. Consulta CONTRIBUTING.md para conocer la estructura del código, cómo ejecutar las pruebas y las peculiaridades de Firefly III que conviene saber antes de tocar nada.

¿Has encontrado un problema de seguridad? Repórtalo de forma privada — consulta SECURITY.md.

Licencia

MIT — consulta LICENSE.