YNAB MCP Server

Servidor MCP de YNAB

Un servidor de Protocolo de Contexto de Modelo (MCP) para una integración perfecta con You Need A Budget (YNAB). Este servidor permite que los asistentes de IA interactúen con tus presupuestos de YNAB, proporcionando potentes capacidades de automatización y análisis.

Instalación Rápida (Claude Desktop)

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here",
      }
    }
  }
}

Variables de entorno opcionales:

"env": {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

Características

• Gestión Completa de Presupuestos

  • Ver y gestionar múltiples presupuestos
  • Rastrear saldos de cuentas y transacciones
  • Monitorear gastos por categoría y metas

• Control de Transacciones

  • Listar y buscar transacciones
  • Actualizar detalles de transacciones
  • Gestionar beneficiarios y categorías

• Análisis Financiero

  • Obtener resúmenes financieros completos
  • Rastrear patrones de gasto
  • Monitorear el progreso del presupuesto

Tabla de Contenidos

• Instalación
• Configuración Específica por Plataforma
• Configuración
• Herramientas Disponibles
• Ejemplos de Uso
• Desarrollo
• Contribuciones
• Licencia

Instalación y Uso

No se necesita instalación cuando se usa uvx:

# Run directly (recommended)
uvx ynab-mcp-server

# Or with specific version
uvx ynab-mcp-server@0.1.1

Para desarrollo:

# Clone and run from source
git clone https://github.com/yourusername/ynab-mcp-server.git
cd ynab-mcp-server
uv run ynab-mcp-server

Configuración Específica por Plataforma

Claude Desktop

1. Localiza tu archivo de configuración:

   • MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Agrega la configuración del servidor MCP de YNAB:

{
  "mcpServers": {
    "ynab-mcp": {
      "command": "uvx",
      "args": ["ynab-mcp-server"],
      "env": {
        "YNAB_PAT": "your_token_here"
      }
    }
  }
}

Variables de entorno opcionales:

env: {
  "YNAB_DEFAULT_BUDGET_ID": "your_budget_id",
  "YNAB_READ_ONLY": "true"
}

Goose

1. Abre la configuración de Goose
2. Navega a la sección de Servidores MCP
3. Agrega un nuevo servidor con:
   • Nombre: ynab-mcp
   • Comando: uvx ynab-mcp-server
   • Variables de Entorno:
     • YNAB_PAT: tu_token_aquí

Otras Plataformas

Para otras plataformas compatibles con MCP, configura usando estos parámetros:

• Nombre del Servidor: ynab-mcp
• Comando: uvx
• Argumentos: ynab-mcp-server
• Variable de Entorno Requerida: YNAB_PAT

Configuración

Tu servidor puede configurarse usando variables de entorno. Puedes colocarlas en un archivo .env en la raíz del proyecto o configurarlas en tu shell.

Variable	Requerida	Descripción
YNAB_PAT	Sí	Tu Token de Acceso Personal de YNAB.
YNAB_DEFAULT_BUDGET_ID	No	Si se establece, el servidor opera en modo de presupuesto único, usando siempre este ID de presupuesto. La herramienta list-budgets estará oculta.
YNAB_READ_ONLY	No	Establecer a true para deshabilitar todas las herramientas que realizan cambios en tus datos de YNAB.

Cómo Obtener Tu Token de YNAB

1. Obtén Tu Token de YNAB

   • Ve a Configuración de Desarrollador de YNAB
   • Crea un nuevo Token de Acceso Personal
   • Copia el valor del token

2. Configura el Entorno

   Crea un archivo .env en tu directorio de trabajo:

   YNAB_PAT="your_token_here"
   YNAB_DEFAULT_BUDGET_ID="your_budget_id"
   YNAB_READ_ONLY="true"
   

   O establece la variable de entorno directamente:

   export YNAB_PAT="your_token_here"
   

Herramientas Disponibles

El servidor proporciona un conjunto de herramientas para interactuar con tus datos de YNAB. Las descripciones explican el propósito y el uso recomendado para cada herramienta.

Herramienta	Descripción
manage-financial-overview	Obtener, actualizar o refrescar un resumen financiero de alto nivel. Este es el mejor punto de partida para cualquier análisis, proporcionando saldos de cuentas, metas y notas de contexto importantes.
list-accounts	Listar todas las cuentas para un presupuesto dado. Útil para obtener IDs de cuentas para otras herramientas.
get-month-info	Obtener información detallada del presupuesto para un solo mes, incluyendo la antigüedad del dinero y los montos totales presupuestados, gastados y disponibles. Llama a esto para verificar el estado del presupuesto mensual antes de hacer cambios.
list-categories	Listar todas las categorías, grupos y sus detalles de presupuestación. Llama a esto antes de gestionar montos presupuestados para ver qué está disponible y qué ya ha sido asignado.
list-transactions	Listar transacciones para una cuenta específica o un mes completo. Usa esto para investigar patrones de gasto identificados en el resumen financiero.
list-scheduled-transactions	Listar todas las transacciones programadas próximas. Útil para pronosticar facturas próximas.
manage-budgeted-amount	Asignar un monto presupuestado a una categoría o mover dinero entre categorías. Esta es la herramienta principal para asignar fondos. (Operaciones de escritura deshabilitadas en modo de solo lectura)
bulk-manage-transactions	Crear, actualizar o eliminar múltiples transacciones a la vez. Más eficiente que hacer cambios individuales. (Operaciones de escritura deshabilitadas en modo de solo lectura)
manage-scheduled-transaction	Crear, actualizar o eliminar una sola transacción programada (recurrente). Usa esto para gestionar facturas recurrentes o transferencias de ahorro. (Operaciones de escritura deshabilitadas en modo de solo lectura)
list-payees	Listar todos los beneficiarios para un presupuesto dado. Bueno para encontrar IDs de beneficiarios o identificar datos de beneficiarios desordenados que necesitan fusionarse.
manage-payees	Fusionar múltiples nombres de beneficiarios en un solo nombre. Usa esto para limpiar datos de beneficiarios. (Operaciones de escritura deshabilitadas en modo de solo lectura)
lookup-entity-by-id	Buscar el nombre y detalles de una cuenta, categoría o beneficiario específico por su ID. Una utilidad para cuando tienes un ID pero necesitas el contexto completo.
lookup-payee-locations	Buscar ubicaciones geográficas asociadas con un beneficiario.
list-budgets	Listar todos los presupuestos de YNAB disponibles (No disponible en modo de presupuesto único).

Desarrollo

Configuración Local

1. Clona el repositorio:

   git clone https://github.com/yourusername/ynab-mcp-server.git
   cd ynab-mcp-server
   

2. Instala las dependencias:

   uv sync
   

3. Ejecuta el servidor:

   uv run ynab-mcp-server
   

Depuración

Usa el Inspector MCP para depurar:

npx @modelcontextprotocol/inspector uvx ynab-mcp-server

Para depuración de desarrollo local:

cd path/to/ynab-mcp-server
npx @modelcontextprotocol/inspector uv run ynab-mcp-server

También puedes ver los registros con:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Compilación y Publicación

# Build package
uv build

# Publish to PyPI
uv publish

Contribuciones

¡Las contribuciones son bienvenidas! Así es como puedes ayudar:

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Haz commit de tus cambios (git commit -m 'Add amazing feature')
4. Haz push a la rama (git push origin feature/amazing-feature)
5. Abre una Solicitud de Extracción (Pull Request)

Por favor, asegúrate de que tu PR:

• Siga el estilo de código existente
• Incluya pruebas apropiadas
• Actualice la documentación según sea necesario

Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.

Agradecimientos

• API de YNAB por proporcionar la funcionalidad principal
• Protocolo de Contexto de Modelo por permitir la integración con asistentes de IA