Servidor MCP para Taiga

Servidor Model Context Protocol (MCP) para interactuar con la API de Taiga desde clientes LLM (Cursor, Open WebUI, Slack MCP, etc.).

Requisitos

• Node.js 24.x (LTS Krypton, usar .nvmrc)
• Acceso a una instancia de Taiga
• Autenticación por token o por usuario/contraseña

Variables de entorno

| Variable | Requerida | Descripción | |---|---|---| | TAIGA_API_URL | Si | URL base de tu instancia Taiga, por ejemplo https://tu-instancia-taiga.com/api/v1 | | TAIGA_TOKEN | Si* | Token de autenticación | | TAIGA_USERNAME | Si* | Usuario de Taiga | | TAIGA_PASSWORD | Si* | Contraseña de Taiga |

* Debes configurar TAIGA_TOKEN o TAIGA_USERNAME + TAIGA_PASSWORD.

Instalacion local

1. Configurar la version de Node.js:

nvm use

2. Instalar dependencias:

pnpm install

3. Compilar:

pnpm build

4. Configurar variables de entorno:

Opción A: token directo

export TAIGA_API_URL="https://tu-instancia-taiga.com/api/v1"
export TAIGA_TOKEN="tu-token-de-taiga"

Opción B: usuario y contraseña

export TAIGA_API_URL="https://tu-instancia-taiga.com/api/v1"
export TAIGA_USERNAME="tu-usuario"
export TAIGA_PASSWORD="tu-contraseña"

Uso desde npm (sin clonar)

Puedes ejecutarlo directamente con npx:

npx -y @dekalabs-npm/taiga-mcp-server

Configuracion en cliente MCP

Este servidor se expone por stdio y funciona con clientes MCP compatibles. Tienes un ejemplo en mcp.config.example.json.

Opción recomendada (con nvm)

{
  "mcpServers": {
    "taiga": {
      "command": "bash",
      "args": [
        "-lc",
        "source ~/.nvm/nvm.sh && nvm use >/dev/null && npx -y @dekalabs-npm/taiga-mcp-server"
      ],
      "env": {
        "TAIGA_API_URL": "https://tu-instancia-taiga.com/api/v1",
        "TAIGA_TOKEN": "tu-token-de-taiga"
      }
    }
  }
}

Opción con usuario y contraseña

{
  "mcpServers": {
    "taiga": {
      "command": "bash",
      "args": [
        "-lc",
        "source ~/.nvm/nvm.sh && nvm use >/dev/null && npx -y @dekalabs-npm/taiga-mcp-server"
      ],
      "env": {
        "TAIGA_API_URL": "https://tu-instancia-taiga.com/api/v1",
        "TAIGA_USERNAME": "tu-usuario",
        "TAIGA_PASSWORD": "tu-contraseña"
      }
    }
  }
}

Flujo recomendado

Antes de usar cualquier otra herramienta, llama a load_project_context con projectSlug o projectId.

1. load_project_context({ projectSlug: "mi-proyecto" })
   -> Devuelve estados, roles, puntos, tags y miembros
2. Usar el resto de herramientas con esos IDs

Herramientas disponibles

Contexto y configuracion

• load_project_context - Inicializa y devuelve configuracion dinamica del proyecto
• get_estimation_taxonomy - Devuelve roles computables y escala de puntos

Creacion

• create_user_story - Crea una historia de usuario
• create_storyless - Crea una tarea sin historia de usuario
• create_task_for_us - Crea una tarea dentro de una historia de usuario

Listado

• list_sprints - Lista sprints activos
• list_users - Lista usuarios (GET /api/v1/users, con filtro opcional por project)
• list_user_stories - Lista historias de usuario con filtros avanzados
• list_tasks - Lista tareas con filtros avanzados
• list_user_stories_from_sprint - Lista historias de usuario de un sprint
• list_tasks_from_user_story - Lista tareas de una historia de usuario

Actualizacion

• update_user_story_status - Actualiza estado de historias de usuario
• update_task_status - Actualiza estado de tareas
• update_user_story_subject - Actualiza titulo de una historia de usuario
• update_user_story_tags - Actualiza tags de una historia de usuario
• update_user_story_points - Actualiza puntos por rol de una historia de usuario
• move_us_to_sprint - Mueve una historia a sprint y la pone en READY

Operaciones masivas

• generate_backlog - Crea multiples historias de usuario con tareas

Parámetros destacados

load_project_context

| Parámetro | Tipo | Requerido | Descripción | |---|---|---|---| | projectSlug | string | Si (o projectId) | Slug del proyecto | | projectId | number | Si (o projectSlug) | ID numerico del proyecto | | forceRefresh | boolean | No | Fuerza recarga del contexto |

list_users

| Parámetro | Tipo | Requerido | Descripción | |---|---|---|---| | project | number | No | ID del proyecto. Si no se indica, usa el proyecto del contexto actual |

Pruebas manuales

pnpm build && pnpm start

El servidor se comunica por stdio; para pruebas funcionales es mejor usarlo desde un cliente MCP.

Estructura del proyecto

.
├── .nvmrc
├── package.json
├── tsconfig.json
├── README.md
├── mcp.config.example.json
└── src/
    ├── index.ts
    ├── config/
    │   └── constants.ts
    ├── client/
    │   ├── TaigaClient.ts
    │   └── TaigaAuth.ts
    ├── types/
    │   └── taiga.ts
    ├── utils/
    │   └── guardrails.ts
    └── tools/
        ├── index.ts
        ├── loadProjectContext.ts
        ├── listUsers.ts
        ├── createUserStory.ts
        ├── createStoryless.ts
        ├── createTaskForUs.ts
        ├── listSprints.ts
        ├── listUserStories.ts
        ├── listTasks.ts
        ├── listUserStoriesFromSprint.ts
        ├── listTasksFromUserStory.ts
        ├── updateUserStoryStatus.ts
        ├── updateTaskStatus.ts
        ├── updateUserStorySubject.ts
        ├── updateUserStoryTags.ts
        ├── updateUserStoryPoints.ts
        ├── moveUsToSprint.ts
        ├── generateBacklog.ts
        └── modules/
            ├── index.ts
            ├── configTools.ts
            ├── createTools.ts
            ├── listTools.ts
            ├── updateTools.ts
            ├── bulkTools.ts
            └── toolHandlers.ts

Scripts

• pnpm build - Compila TypeScript a JavaScript
• pnpm start - Ejecuta el servidor compilado
• pnpm dev - Compila y ejecuta en un solo paso
• pnpm watch - Watch mode
• pnpm clean - Limpia dist

Notas importantes

1. load_project_context debe llamarse al inicio de cada sesion.
2. El contexto del proyecto se cachea en memoria (estados, roles, puntos, tags, miembros).
3. El servidor usa control de version optimista de Taiga en operaciones PATCH.

Soporte

Si necesitas soporte técnico con este proyecto, contacta a Luis Ballester Zafra - Dekalabs.

Troubleshooting

1. Verifica que TAIGA_API_URL y las credenciales estén configuradas.
2. Revisa logs de error en stderr.
3. Asegura Node.js 24.x (LTS Krypton).
4. Verifica dependencias instaladas con pnpm install.
5. Asegurate de llamar load_project_context antes de otras herramientas.