Ledger CLI

mcp-server-ledger: Un servidor MCP para Ledger CLI

Resumen

Un servidor del Protocolo de Contexto de Modelos (MCP) para interactuar con Ledger CLI, un potente sistema de contabilidad de partida doble accesible desde la línea de comandos. Este servidor permite que los Modelos de Lenguaje de Gran Tamaño consulten y analicen tus datos financieros a través de la herramienta Ledger CLI.

Este servidor MCP expone la funcionalidad de Ledger CLI a través de una interfaz estandarizada, lo que facilita que los asistentes de IA te ayuden con informes financieros, análisis de presupuestos y tareas contables.

Características

El servidor proporciona las siguientes herramientas que se corresponden con los comandos de Ledger CLI:

1. ledger_balance

   • Muestra los saldos de las cuentas con potentes opciones de filtrado
   • Entradas: patrón de consulta, rangos de fechas, opciones de visualización
   • Devuelve: Informe de saldos formateado

2. ledger_register

   • Muestra el registro de transacciones con historial detallado
   • Entradas: patrón de consulta, rangos de fechas, opciones de ordenación
   • Devuelve: Informe de registro formateado

3. ledger_accounts

   • Lista todas las cuentas en el archivo de contabilidad
   • Entrada: patrón de consulta opcional
   • Devuelve: Lista de cuentas coincidentes

4. ledger_payees

   • Lista todos los beneficiarios de las transacciones
   • Entrada: patrón de consulta opcional
   • Devuelve: Lista de beneficiarios coincidentes

5. ledger_commodities

   • Lista todos los commodities (monedas) utilizados
   • Entrada: patrón de consulta opcional
   • Devuelve: Lista de commodities coincidentes

6. ledger_print

   • Imprime transacciones en formato de contabilidad
   • Entradas: patrón de consulta, rangos de fechas
   • Devuelve: Entradas de contabilidad formateadas

7. ledger_stats

   • Muestra estadísticas sobre el archivo de contabilidad
   • Entrada: patrón de consulta opcional
   • Devuelve: Resumen estadístico de la contabilidad

8. ledger_budget

   • Muestra análisis de presupuesto
   • Entradas: patrón de consulta, rangos de fechas, período de informe
   • Devuelve: Informe de presupuesto

9. ledger_raw_command

   • Ejecuta un comando Ledger CLI sin procesar
   • Entrada: argumentos de comando como una lista de cadenas
   • Devuelve: Salida del comando como texto

Requisitos previos

• Ledger CLI debe estar instalado y disponible en tu PATH
• Un archivo Ledger válido con tus datos financieros

Instalación

Usando Docker (recomendado)

También puedes usar la imagen de Docker del repositorio minhyeoky/mcp-ledger:

docker pull minhyeoky/mcp-ledger

Añade esto a tu claude_desktop_config.json:

"mcp-ledger": {
  "command": "docker",
  "args": [
    "run",
    "-v",
    "/path/to/your/ledger/file.ledger:/main.ledger",
    "-e",
    "LEDGER_FILE=/main.ledger",
    "-i",
    "--rm",
    "minhyeoky/mcp-ledger"
  ]
}

Reemplaza /path/to/your/ledger/file.ledger con la ruta real a tu archivo de contabilidad.

Instalación vía Smithery

Para instalar Ledger CLI MCP Server para Claude Desktop automáticamente a través de Smithery:

npx -y @smithery/cli install @minhyeoky/mcp-ledger --client claude

Usando uv

La forma más fácil de instalar y ejecutar este servidor es con uv:

uv sync

Configuración

El servidor requiere una ruta a tu archivo Ledger. Esto se puede proporcionar a través de:

• La variable de entorno LEDGER_FILE
• Argumentos de línea de comandos al iniciar el servidor

Uso con Claude Desktop

Añade esto a tu claude_desktop_config.json:

"mcpServers": {
  "ledger": {
    "command": "uv",
    "args": [
      "run",
      "--env-file",
      "/path/to/your/.env",  // Optional: to set LEDGER_FILE
      "--with",
      "mcp[cli]",
      "mcp",
      "run",
      "<repo_path>/main.py"  // Path to the main.py file in this repository
    ]
  }

}

Ejemplos de uso

Una vez configurado, puedes hacer preguntas a tu asistente de IA sobre tus datos financieros:

• "Muéstrame mis gastos del último mes"
• "¿Cuál es mi saldo actual en todas las cuentas?"
• "Lista todas las transacciones con Amazon"
• "¿Cuánto gasté en comestibles en 2023?"
• "Muéstrame mi rendimiento presupuestario del primer trimestre"

La IA utilizará los comandos Ledger CLI apropiados a través del servidor para obtener la información.

Depuración

Para pruebas locales más detalladas:

mcp dev main.py

Desarrollo

Este servidor está construido con el Model Context Protocol Python SDK. Para más información sobre MCP y cómo desarrollar servidores MCP, consulta la documentación oficial.

Para contribuir a este proyecto:

1. Clona el repositorio
2. Instala las dependencias de desarrollo
3. Realiza tus cambios
4. Prueba usando el inspector MCP o integrando con Claude Desktop

Consideraciones de seguridad

Este servidor ejecuta comandos Ledger CLI sobre tus datos financieros. Aunque incluye validación básica para prevenir la inyección de comandos, debes:

• Usarlo solo con clientes de confianza
• Tener cuidado con las rutas de archivos que expones
• Revisar todos los comandos antes de ejecutarlos

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Siéntete libre de usarlo, modificarlo y distribuirlo según los términos de la licencia.