Servidor MCP de Firefly III

Un servidor MCP (Model Context Protocol) que le da a Claude acceso total a tu instancia de finanzas personales de Firefly III. Habla con Claude en lenguaje natural para registrar gastos, consultar saldos, gestionar presupuestos y más.

Características

• Transacciones: Crear, listar, buscar, actualizar y eliminar transacciones (retiros, depósitos, transferencias)

• Cuentas: Gestionar cuentas de activos, gastos, ingresos, pasivos y efectivo

• Categorías: Organizar transacciones con categorías

• Presupuestos: Crear y gestionar presupuestos con soporte de presupuesto automático

• Etiquetas: Etiquetar transacciones con etiquetas flexibles

Requisitos previos

• Node.js >= 18

• Una instancia de Firefly III en ejecución

• Un Token de Acceso Personal (PAT) de tu instancia de Firefly III

Cómo obtener tu PAT

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

2. Ve a Opciones → Perfil → OAuth

3. En Tokens de Acceso Personal, crea un nuevo token

4. Copia el token: lo necesitarás para la configuración

Instalación

Vía npm (recomendado)

npm install -g firefly-iii-mcp-server

Desde el código fuente

git clone https://github.com/przbadu/firefly-iii-mcp-server.git
cd firefly-iii-mcp-server
npm install
npm run build

Configuración

Claude Desktop

Edita tu archivo de configuración de Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Usando el binario instalado por npm:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "firefly-iii-mcp-server",
      "env": {
        "FIREFLY_III_URL": "https://your-firefly-instance.example.com",
        "FIREFLY_III_PAT": "your-personal-access-token-here"
      }
    }
  }
}

O usando npx (no se requiere instalación global):

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": ["-y", "firefly-iii-mcp-server"],
      "env": {
        "FIREFLY_III_URL": "https://your-firefly-instance.example.com",
        "FIREFLY_III_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Claude Code CLI

claude mcp add firefly-iii \
  -e FIREFLY_III_URL=https://your-firefly-instance.example.com \
  -e FIREFLY_III_PAT=your-personal-access-token-here \
  -- npx -y firefly-iii-mcp-server

O añádelo a tu .claude/settings.json:

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": ["-y", "firefly-iii-mcp-server"],
      "env": {
        "FIREFLY_III_URL": "https://your-firefly-instance.example.com",
        "FIREFLY_III_PAT": "your-personal-access-token-here"
      }
    }
  }
}

Ejemplos de uso

Una vez configurado, simplemente habla con Claude de forma natural:

Registro de transacciones

"Gasté $45.50 en Trader Joe's en comestibles hoy"

"Registra un depósito de salario de $2,500 de mi empleador en mi cuenta corriente"

"Transfiere $500 de la cuenta corriente a la de ahorros"

Consultas

"Muéstrame todas mis transacciones de la semana pasada"

"¿Cuánto gasté en restaurantes este mes?"

"¿Cuál es el saldo de mi cuenta corriente?"

Gestión de finanzas

"Crea un presupuesto mensual de comestibles de $600"

"Lista todas mis categorías de gastos"

"Etiqueta mis últimas 3 transacciones de restaurante como 'comidas de negocios'"

Herramientas disponibles

Desarrollo

# Watch mode with auto-reload
npm run dev

# Build for production
npm run build

# Run the built server
npm start

Licencia

MIT