amulen-mcp-server

Servidor MCP (Model Context Protocol) para integración con AMULEN — Sistema de Gestión de Proyectos

Permite a clientes MCP (Kiro, Claude Desktop, Cursor, Zed, etc.) interactuar con la API REST de AMULEN para gestionar proyectos, tableros, tareas y comentarios.

Features

• Gestión de proyectos — crear, actualizar, listar proyectos y consultar dashboards con métricas
• Tableros y tareas — CRUD completo de tableros y tareas, mover estados (kanban), filtros por estado/fecha/usuario
• Mis tareas — consulta cross-proyecto de tareas asignadas al usuario autenticado
• Comentarios — agregar comentarios a tareas
• Dual format — respuestas JSON por defecto; 5 tools de lectura soportan markdown opcional (optimizado para agentes)

Requisitos previos

1. uv instalado
2. Python >= 3.12
3. Cuenta activa en una instancia de AMULEN

Validar la instalación

Para validar la instalación, ejecuta el siguiente comando:

uvx amulen-mcp-server --version

Instalación rápida

Configuración en MCP Clients

Variables de entorno requeridas

Variables opcionales:

Kiro CLI

Archivo .kiro/settings/mcp.json:

{
  "mcpServers": {
    "amulen-mcp-server": {
      "command": "uvx",
      "args": ["amulen-mcp-server@latest"],
      "env": {
        "AMULEN_BASE_URL": "${AMULEN_BASE_URL}",
        "AMULEN_EMAIL": "${AMULEN_EMAIL}",
        "AMULEN_PASSWORD": "${AMULEN_PASSWORD}"
      }
    }
  }
}

La sintaxis ${VARIABLE} referencia variables de entorno de tu shell. Configúralas antes de iniciar el cliente:

export AMULEN_BASE_URL="https://mi-empresa.amulen.app"
export AMULEN_EMAIL="usuario@empresa.com"
export AMULEN_PASSWORD="tu-contraseña"

Más detalles en la documentación de Kiro CLI — MCP Configuration.

El mismo formato aplica para Claude Desktop, Cursor, Zed y otros clientes MCP compatibles.

Nota: La sintaxis ${VAR} está verificada en Kiro CLI. En otros clientes (Claude Desktop, Cursor, Zed) es posible que las credenciales deban ir hardcodeadas en el JSON de configuración. Si es tu caso, consulta la documentación de tu cliente MCP para la forma recomendada de manejar secretos. Hardcodear credenciales funciona pero no es recomendable.

Seguridad

• Usa referencias a variables de entorno (${VAR}) en vez de valores hardcodeados en archivos de configuración
• No commitees archivos de configuración con credenciales a control de versiones
• Agrega mcp.json y claude_desktop_config.json a tu .gitignore

Tools disponibles (19)

Lectura

• amulen_health — Verificar conectividad e identificar usuario autenticado
• amulen_list_projects — Listar todos los proyectos
• amulen_get_project — Obtener detalles de un proyecto
• amulen_get_project_dashboard — Métricas y dashboard de un proyecto
• amulen_list_boards — Listar tableros de un proyecto
• amulen_get_board — Obtener detalles de un tablero
• amulen_list_tasks — Listar tareas de un tablero con filtros opcionales
• amulen_get_task — Obtener detalles de una tarea (con include_details para comentarios y checklist)
• amulen_my_tasks — Listar mis tareas asignadas (cross-proyecto)

Escritura

• amulen_create_project — Crear un nuevo proyecto
• amulen_update_project — Actualizar un proyecto existente
• amulen_create_board — Crear un nuevo tablero
• amulen_create_task — Crear una nueva tarea
• amulen_update_task — Actualizar una tarea existente
• amulen_move_task_state — Mover tarea a otro estado (TO DO, DOING, DONE, PENDING, BACKLOG)
• amulen_add_comment — Agregar comentario a una tarea
• amulen_create_checklist_item — Crear item de checklist en una tarea
• amulen_update_checklist_item — Actualizar item de checklist (título, descripción o marcar completado)
• amulen_delete_checklist_item — Eliminar item de checklist de una tarea

Formato de respuesta

14 tools devuelven solo JSON. 5 tools de lectura (list_projects, list_boards, list_tasks, my_tasks, get_task) soportan response_format: "markdown" (default, optimizado para agentes) o "json" (datos estructurados).

Desarrollo

git clone <repo-url>
cd amulen-mcp-server
uv sync
uv run mcp dev -e . src/amulen_mcp_server/server_core.py:app

Licencia

MIT