Firefly III MCP Server

Servidor MCP de Firefly III

Un servidor del Protocolo de Contexto de Modelos (MCP) que brinda a un asistente de IA acceso a tu propia instancia de Firefly III: 152 operaciones detrás de 5 herramientas con alcance definido, con lectura, escritura y eliminación mantenidas como tres superficies separadas y explícitamente autorizadas, en lugar de una sola herramienta que pueda hacer las tres cosas.

Türkçe: README.tr.md

• "¿En qué gasté más el mes pasado?"
• "Encuentra transacciones sin categorizar de agosto y sugiere categorías."
• "Muéstrame suscripciones cuyo importe haya aumentado."

Cada persona ejecuta esto contra su propia instancia de Firefly con su propio token: no hay un backend alojado ni un intermediario en el medio.

Listado en el Registro MCP oficial como io.github.YakupEmreYerli/mcp-firefly-iii, en Glama y en la documentación de aplicaciones de terceros del propio Firefly III. Cada versión se compila y publica mediante CI a partir de un commit etiquetado, con procedencia npm que certifica que el paquete proviene de este repositorio.

Demostración

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

Demostración de 38 segundos: haz una pregunta financiera, lee la respuesta a través de MCP, previsualiza un cambio con dry_run, aprueba y escríbelo de vuelta a Firefly III. Grabado contra una instancia sintética: todos los datos financieros mostrados son ficticios.

Características

• 5 metaherramientas, no 152. firefly_query, firefly_mutate, firefly_destructive, además de firefly_list_operations y firefly_get_schema para descubrimiento: un registro tipado asigna cada endpoint de Firefly a estas herramientas en lugar de inundar la lista de herramientas del modelo.
• dry_run en cada escritura, devolviendo la solicitud exacta (incluidos los ID de registros resueltos) sin enviarla.
• Las escrituras masivas no pueden ejecutarse a ciegas. Las actualizaciones basadas en filtros requieren max_matches y rechazan un escaneo incompleto antes de la primera escritura; los grupos de transacciones con múltiples divisiones se rechazan directamente en lugar de arriesgarse a combinar sus importes.
• Lectura/escritura/destructivo están separados por alcance y se aplican, no solo se anotan: a través de stdio con el token de Firefly, a través de HTTP con alcance OAuth o un token estático.
• Servidor de autorización OAuth 2.1 integrado para Claude web, Claude móvil y ChatGPT: sin instalación separada de Keycloak o Authentik.
• Imágenes Docker para linux/amd64/linux/arm64 y una canalización de documentación autoverificable que mantiene el catálogo de herramientas sincronizado con el código.
• Te avisa cuando está desactualizado. Una vez al día comprueba si existe una versión más reciente y, si es así, lo dice una vez: una línea en stderr, una frase junto a la siguiente respuesta. MCP_UPDATE_CHECK=false lo desactiva.

Requisitos previos

• Una instancia de Firefly III en ejecución y un Token de Acceso Personal (Firefly III → Opciones → Perfil → OAuth → Crear nuevo Token de Acceso Personal)
• Node.js 20.6+, a menos que uses Docker

Uso

Método	Transporte	Mejor para
npx — stdio	stdio	Claude Code, Claude Desktop, Cursor: configuración más sencilla
Token estático	HTTP	n8n, automatización, llamadas sin interfaz
OAuth	HTTP + OAuth	Claude web, Claude móvil, ChatGPT: no pueden mantener un token estático
Docker	HTTP	Autohospedado, cualquiera de los modos de autenticación anteriores

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

Deja que la configuración lo haga: pregunta por la dirección y el token de Firefly III, comprueba que realmente funcionan y luego configura Claude Code y Claude Desktop si los encuentra: npx -y @yakupemreyerli/firefly-mcp setup. Para cualquier otro cliente, imprime la configuración para pegarla.

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

A mano, Claude Desktop / Cursor / otros clientes: agrega al archivo de configuración 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 con token estático

Para n8n, automatización o cualquier llamador que no pueda manejar un flujo OAuth basado en navegador. Configura MCP_HTTP_TOKEN en .env y luego ejecuta npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http. Cada solicitud a /mcp debe llevar Authorization: Bearer <token>: un token, acceso completo, sin alcance por conexión.

3. HTTP remoto con OAuth (Claude web, Claude móvil, ChatGPT)

Ninguno de estos clientes puede mantener un token estático y ninguno puede generar un proceso local: se conectan a una URL HTTPS pública y esperan OAuth. Con MCP_AUTH_PASSWORD configurado, este servidor es el servidor de autorización OAuth 2.1: maneja el registro de clientes, PKCE y el intercambio de tokens por sí mismo, por lo que no hay Keycloak, ni inicio de sesión con Google, ni token que copiar en ningún lugar.

Paso 1: dale al servidor una dirección HTTPS pública. Cloudflare Tunnel es la ruta más fácil para un servidor doméstico (sin reenvío de puertos, sin certificado); Caddy o Traefik funcionan en un VPS. compose.example.yml incluye perfiles cloudflare y caddy exactamente para esto. Supongamos que el resultado es https://mcp.example.com.

Paso 2: configura .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 es el origen externo, carácter por carácter, sin ruta — no el http://firefly-mcp:3000 interno, ni la URL de conexión /mcp. Una discrepancia falla la verificación de audiencia del token y el cliente solo informa "token no válido". MCP_AUTH_STATE_DIR debe estar en un volumen persistente (compose.example.yml monta uno) o cada reinicio desautoriza a todos los clientes.

Paso 3: inícialo y verifica:

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

Si auth dice bearer en su lugar, la contraseña nunca llegó al proceso y el cliente informará que el servidor no admite OAuth.

Paso 4a: Claude (web, Desktop, iOS/Android). Configuración → Conectores → Agregar conector personalizado, URL https://mcp.example.com/mcp. Deja las opciones de autenticación como se detecten: Claude sondea el servidor y elige el flujo que admite. El conector funciona entonces en todas las superficies de Claude donde hayas iniciado sesión, incluido el teléfono.

Paso 4b: ChatGPT. En la pantalla de conector personalizado / MCP, ingresa el mismo https://mcp.example.com/mcp y elige OAuth como método de autenticación.

Paso 5: ingresa la contraseña. Se abre una pantalla de inicio de sesión de Firefly en el navegador; escribe MCP_AUTH_PASSWORD. Esa única pantalla es toda la decisión: la conexión recibe los tres alcances (firefly:read, firefly:write, firefly:destructive), sea lo que sea que el propio cliente haya solicitado. No hay una segunda pantalla de consentimiento: quien tenga la contraseña podría haber marcado todas las casillas. Para otorgar una conexión que realmente no pueda escribir, dale al servidor un Token de Acceso Personal de Firefly de solo lectura.

Recetas TLS completas y solución de problemas: docs/oauth.md.

4. Docker

Recomendado para cualquiera de los modos HTTP anteriores:

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

Cambia build: . en compose.example.yml por image: ghcr.io/yakupemreyerli/mcp-firefly-iii:latest para usar la imagen precompilada: fija una etiqueta de versión, no :latest, para cualquier cosa de la que dependas. Contenedor único sin Compose: docker run -d --env-file .env -p 3000:3000 ghcr.io/yakupemreyerli/mcp-firefly-iii:latest. Se niega a iniciar sin uno de los dos modos de autenticación anteriores, y /mcp necesita TLS al frente: compose.example.yml tiene perfiles opcionales cloudflare y caddy para eso. /health está abierto, para sondeos de contenedores.

Configuración

Variable	Predeterminado	Propósito
FIREFLY_API_URL	—	Obligatorio. Un dominio simple o una URL base completa que incluya /api/v1.
FIREFLY_API_TOKEN	—	Obligatorio. Token de Acceso Personal.
FIREFLY_DISABLE_SSL_VERIFY	false	Solo para una instancia local con un certificado autofirmado.
MCP_UPDATE_CHECK	true	Verificación diaria de una versión más reciente. La única solicitud que este servidor hace a cualquier lugar que no sea tu instancia de Firefly, y no lleva datos.

Cada variable, incluidos los modos HTTP y OAuth: docs/configuration.md.

Herramientas

Herramienta	Responde	Riesgo
firefly_query	Lee cualquier cosa. Su descripción lleva el catálogo, por lo que elegir una operación no cuesta una llamada adicional.	solo lectura
firefly_mutate	Crea o cambia un registro.	escrituras
firefly_destructive	Elimina un registro o reescribe un campo en muchos registros a la vez.	no se puede deshacer
firefly_list_operations	¿Qué puedo hacer con esta entidad?	solo lectura
firefly_get_schema	¿Qué parámetros toma esta operación?	solo lectura

La división se aplica, no solo se anuncia: una eliminación alcanzada a través de firefly_query se rechaza, y una conexión con solo firefly:read nunca ve siquiera las dos herramientas de escritura. Las respuestas se recortan antes de llegar al modelo: los atributos vacíos y nulos siempre se eliminan, y cada herramienta de ejecución toma una lista fields: aproximadamente un recorte del 90 % en una lista grande de transacciones. Referencia completa: docs/api/operations.md.

Seguridad

Este servidor nunca envía tus datos a un tercero, pero no controla lo que el cliente de IA o el modelo al que lo conectas hace con una respuesta una vez que la tiene. Modelo de amenazas completo: SECURITY.md. ¿Encontraste una vulnerabilidad? Repórtala de forma privada allí.

Documentación

Página	Qué cubre
Inicio rápido	Obtener un token, conectar tu cliente, primeras cosas para probar, solución de problemas
Configuración	Cada variable de entorno, la política de permisos, el modo HTTP
Acceso remoto con OAuth integrado	Implementación para Claude web, Claude móvil y ChatGPT
Integración MCP	Claude Code, Claude Desktop, Cursor, VS Code, n8n y HTTP remoto
Operaciones	Las 152 operaciones, el recorte de respuestas, las peculiaridades de Firefly que afectan
Operaciones de análisis	summary.overview, búsqueda y los ocho endpoints de información
Inspector MCP	Probar el servidor de forma interactiva durante el desarrollo

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 cada operación de lectura contra la instancia en .env; es de solo lectura y no forma parte del paquete publicado. Los informes de errores y las solicitudes de extracción son bienvenidos: consulta CONTRIBUTING.md.

Licencia

MIT: consulta LICENSE.