Firefly III MCP Server

Este es un servidor del Protocolo de Contexto de Modelo (MCP) para Firefly III, un gestor de finanzas personales gratuito y de código abierto. A través de este servidor MCP, los usuarios pueden utilizar herramientas de IA para gestionar sus cuentas y transacciones de Firefly III, creando asistentes de IA para las finanzas personales y la contabilidad.

Ver versión en chino

Estructura del proyecto

Este proyecto utiliza una estructura de monorepo gestionada con Turborepo, que contiene los siguientes paquetes principales:

• @firefly-iii-mcp/core: módulo de funcionalidad principal que proporciona la base para interactuar con la API de Firefly III.

• @firefly-iii-mcp/local: herramienta de línea de comandos para ejecutar el servidor MCP localmente.

• @firefly-iii-mcp/cloudflare-worker: implementación para el despliegue en Cloudflare Workers.

• @firefly-iii-mcp/server: implementación de servidor basada en Express con soporte para Streamable HTTP y SSE.

Related MCP server: Firefly III MCP Server

Características

• Interactúa con instancias de Firefly III mediante IA.

• Gestiona cuentas y transacciones de forma programática.

• Conjunto de herramientas extensible para diversas operaciones financieras.

• Soporte tanto para despliegue local como en la nube.

• Compatible con el estándar del Protocolo de Contexto de Modelo.

• Filtrado de herramientas mediante preajustes o etiquetas personalizadas para reducir el uso de tokens.

Requisitos previos

• Una instancia de Firefly III en funcionamiento.

• Una cuenta de Cloudflare si planeas desplegar usando el botón "Deploy to Cloudflare".

Primeros pasos

1. Obtener un token de acceso personal (PAT) de Firefly III

Para permitir que el servidor MCP interactúe con tu instancia de Firefly III, debes generar un token de acceso personal (PAT):

1. Inicia sesión en tu instancia de Firefly III.

2. Navega a Opciones > Perfil > OAuth.

3. En la sección "Tokens de acceso personal", haz clic en "Crear nuevo token".

4. Dale a tu token un nombre descriptivo (por ejemplo, "Token del servidor MCP").

5. Haz clic en "Crear".

6. Importante: copia el token generado de inmediato. No podrás volver a verlo.

Para obtener más detalles, consulta la documentación oficial de Firefly III sobre tokens de acceso personal.

2. Configurar el servidor MCP

Debes proporcionar el PAT de Firefly III y la URL de tu instancia de Firefly III al servidor MCP. Esto se puede hacer de varias maneras:

Cabeceras de solicitud (recomendado)

Proporciona estos valores en las cabeceras de cada solicitud al servidor MCP. Generalmente, es el método más seguro:

• X-Firefly-III-Url: la URL de tu instancia de Firefly III (por ejemplo, https://firefly.yourdomain.com).

• Authorization: el token de acceso personal, normalmente con el prefijo Bearer (por ejemplo, Bearer YOUR_FIREFLY_III_PAT).

Consulta la documentación de la herramienta o del cliente de IA que estés usando para conocer los nombres exactos de las cabeceras que espera.

Parámetros de consulta (usar con precaución)

También puedes proporcionar estos valores en los parámetros de consulta de cada solicitud al servidor MCP:

• baseUrl: la URL de tu instancia de Firefly III.

• pat: tu token de acceso personal de Firefly III.

Ten en cuenta que las URL, incluidos los parámetros de consulta, pueden quedar registradas en varios lugares, lo que podría exponer información sensible.

Variables de entorno (principalmente para autohospedaje o desarrollo local)

Establece las siguientes variables de entorno antes de ejecutar la base de datos:

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

Ejecutar el servidor MCP

Método 1: Modo local

Este método es adecuado para clientes que admiten llamar a herramientas MCP mediante la entrada/salida estándar (stdio), como Claude Desktop.

Comando básico de ejecución:

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

También puedes filtrar las herramientas disponibles para reducir el uso de tokens:

# Using a preset
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget

# Using custom tool tags
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories

También puedes consultar el tutorial oficial para la configuración en formato JSON.

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>",
        "--preset",
        "default"
      ]
    }
  }
}

Método 2: Servidor Express (recomendado para aplicaciones web)

Este método proporciona un servidor basado en HTTP con soporte para Streamable HTTP y SSE, lo que lo hace ideal para aplicaciones web.

Como herramienta de línea de comandos

npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

Para conocer las opciones disponibles:

• -p, --pat <token>: token de acceso personal de Firefly III.

• -b, --baseUrl <url>: URL base de Firefly III.

• -P, --port <number>: puerto de escucha (predeterminado: 3000).

• -l, --logLevel <level>: nivel de registro: debug, info, warn, error (predeterminado: info).

• -s, --preset <name>: preajuste de herramientas a utilizar (default, full, basic, budget, prêt à, admin, automation).

• -t, --tools <list>: lista de etiquetas de herramientas a habilitar, separadas por comas.

Como biblioteca

npm install @firefly-iii-mcp/server

Uso básico:

import { createServer } from '@firefly-iii-mcp/server';

const server = createServer({
  port: 3000,
  pat: process.env.FIREFLY_III_PAT,
  baseUrl: process.env.FIREFLY_III_BASE_URL,
  enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
});

server.start().then(() => {
  console.log('MCP Server is running on http://localhost:3000');
});

Para obtener más detalles, consulta la documentación de @firefly-iii-mcp/server.

Método 3: Desplegar en Cloudflare Workers (recomendado para producción)

Puedes desplegar fácilmente este servidor MCP en Cloudflare Workers con el siguiente botón:

Nota: después de desplegarlo, deberás configurar las variables de entorno en la configuración de tu Worker de Cloudflare:

1. Ve a tu panel de Cloudflare.

2. Navega a Workers & Pages.

3. Selecciona el Worker desplegado.

4. Ve a Configuración > Variables.

5. Añade las siguientes variables:

• Obligatorias: FIREFLY_III_BASE_URL y FIREFLY_III_PAT.

• Opcional: FIREFLY_III_PRESET o FIREFLY_III_TOOLS.

Método 4: Ejecutar localmente desde el código fuente

[!NOTE] Para uso en producción, se recomienda utilizar el paquete npm o desplegar en Cloudflare Workers.

1. Clona el repositorio:

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp

2. Instala las dependencias:

   npm install

3. Crea un archivo .env:

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   # Optional: Filter tools
   FIREFLY_III_PRESET="default"
   # Or
   FIREFLY_III_TOOLS="accounts,transactions,categories"

4. Compila el proyecto:

   npm run build

5. Inicia el servidor de desarrollo:

   npm run dev

Opciones de filtrado de herramientas

Puedes filtrar qué herramientas se exponen al cliente MCP para reducir el uso de tokens y centrarte en una funcionalidad específica:

Preajustes disponibles

• default: herramientas básicas para el uso cotidiano (cuentas, facturas, categorías, etiquetas, transacciones, búsqueda y resumen).

• full: todas las herramientas disponibles.

• basic: herramientas básicas de gestión financiera.

• budget: herramientas centradas en presupuestos.

• reporting: herramientas de informes y análisis.

• admin: herramientas de administración.

• automation: herramientas relacionadas con la automatización.

Guía de desarrollo

Este proyecto utiliza Turborepo para gestionar el flujo de trabajo del monorepo y Changesets para el control de versiones y la publicación.

Comandos comunes

• Compilar todos los paquetes: npm run build

• Compilar paquetes específicos: npm run build:core o npm run build:local

• Limpiar artefactos de compilación: npm run clean

• Modo de desarrollo: npm run dev

• Publicar paquetes: npm run publish-packages

Para obtener directrices de desarrollo detalladas, puedes consultar la guía de contribución.

Agradecimientos

Este proyecto se basa y modifica scripts de generación de harsha-iiiv/openapi-mcp-generator. Muchas gracias a los autores originales por su trabajo.

Contribuciones

¡Las contribuciones son bienvenidas! Este proyecto utiliza Turborepo para gestionar el flujo de trabajo del monorepo. Consulta CONTRIBUTING.md para conocer las pautas detalladas sobre cómo contribuir.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.