Taiga MCP Server

Servidor de Model Context Protocol (MCP) para la gestión de proyectos de Taiga, escrito en TypeScript y construido sobre el Model Context Protocol SDK con transporte stdio (con un transporte HTTP transmisible opcional para clientes remotos y web). Conecta clientes LLM a instancias de Taiga para inspeccionar y gestionar proyectos, elementos de trabajo (incidencias, historias de usuario, tareas, épicas), sprints, comentarios, adjuntos y páginas de wiki.

El servidor concentra todas sus capacidades en 6 herramientas de despacho de operaciones diseñadas para un coste mínimo de tokens y respuestas de texto densas, legibles tanto por humanos como por LLM.

Contenido

• Características · Requisitos y configuración · Inicio rápido · Checkout local · Transporte HTTP y clientes web · Contenedores

• Instalación: Claude Code · Claude Desktop · VS Code / Copilot · Cursor · Windsurf · Cline / Roo / Kilo · Continue.dev · Zed · JetBrains · Gemini CLI · Codex CLI · opencode · Amp · Pi · Oh My Pi

• Herramientas: Convenciones · Por qué seis herramientas · Referencia de herramientas: projects · work · sprints · comments · attachments · wiki

• Operaciones: Fiabilidad · Consideraciones de seguridad · FAQ · Reparación de problemas · Desarrollo · Contribuciones · Registro de cambios · Licencia

Related MCP server: @illodev/taiga-mcp

Características

• Seis herramientas, veintiocho pares de operaciones en proyectos, elementos de trabajo, sprints, comentarios, adjuntos y páginas wiki; toda la carga útil de tools/list es de ~10,493 caracteres (~2,800 tokens).

• Identificadores sencillos en todas partes: proyectos por ID o slug, elementos de trabajo por ID de base de datos o #reference, miembros por ID, nombre de usuario, nombre completo o "me"; estados, prioridades, severidades, tipos de incidencia y nombres de sprint se resuelven en el servidor.

• Salida de texto densa: una línea por registro en los listados y vistas de detalle limpias tipo clave-valor; las colecciones vacías se comunican como datos, no como errores.

• Creación en lote de hasta 20 elementos de trabajo en una sola llamada; los borrados son deliberadamente de un solo elemento.

• Fiabilidad reforzada: reintentos por límite de peticiones con respeto por Retry-After, tiempos de espera HTTP de 30 segundos, caché de metadatos de 60 segundos y ningún reenvío automático ante errores 5xx (las solicitudes mutantes pueden haberse aplicado).

• Seguridad de adjuntos: descargas restringidas a nombres de host concretos, límite de 10 MB, protección frente a sobrescritura y no se envía el token portador a los hosts de medios.

• Doble transporte: stdio por defecto; HTTP transmutable en bucle local cuando TAIGA_HTTP_PORT está definido.

Requisitos y configuración

• Node.js >= 20.11

• Una cuenta de Taiga en taiga.io o una instancia de Taiga autoalojada

• Las tres variables de entorno siguientes:

Variables de transporte opcionales:

Inicio rápido

La forma más rápida es Claude Desktop con npx (sin necesidad de clonar nada):

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Todas las configuraciones de integración que vienen a continuación siguen esta misma estructura; solo cambia la ubicación del archivo y la sintaxis del contenedor.

Credenciales y .env: un checkout local carga automáticamente el .env de la raíz del repositorio (consulta .env.example). La instalación con npx no lo hace: dotenv resuelve las rutas relative a la ubicación de instalación del paquete dentro de la caché de npm, por lo que las credenciales pasadas mediante npx deben indicarse en el bloque de env de cada integración, como se muestra arriba.

Ejecutar desde el checkout local

git clone https://github.com/negoro26/mcp-taiga.git
cd mcp-taiga && npm ci && npm run build
cp .env.example .env   # fill in TAIGA_USERNAME / TAIGA_PASSWORD

Después apunta cualquier integración al punto de entrada compilado en lugar de a npx:

{
  "mcpServers": {
    "taiga": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-taiga/dist/src/index.js"]
    }
  }
}

Aquí no hace falta bloque env: el servidor carga su propio .env desde la raíz del repositorio. Este repositorio también incluye un .mcp.json listo para usar, de modo que los agentes de codificación abiertos dentro del checkout pueden usar la compilación local directamente.

Instalación y configuración

Configuración por integración con el paquete npm publicado. Cada fragmento pasa las credenciales en env vars; usa tus propios valores.

Claude Code

Ámbito de proyecto (dentro del repositorio, compartido con el equipo):

// .mcp.json at repository root
{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

O desde la CLI (ámbito de usuario con -s user; ámbito local por defecto):

claude mcp add taiga \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  -- npx -y mcp-taiga

Compruébalo con claude mcp list o con /mcp dentro de una sesión.

Claude Desktop

Edita el archivo de configuración — claude_desktop_config.json mediante Claude Desktop → Configuración → Desarrollador → Editar configuración, situado en %APPDATA%\Claude\claude_desktop_config.json en Windows o en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS — y reinicia la aplicación de escritorio:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

En Windows, ejecuta npx mediante cmd /c si la forma directa falla: "command": "cmd", "args": ["/c", "npx", "-y", "mcp-taiga"].

VS Code y GitHub Copilot

VS Code admite servidores MCP de forma nativa (1.99+); Copilot Chat los recoge automáticamente.

// .vscode/mcp.json (workspace) or use Command Palette: "MCP: Add Server"
{
  "servers": {
    "taiga": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Puedes iniciarlos desde la vista de extensiones (mcp.json muestra un botón de Start) o ejecutar MCP: Listar servidores en la Paleta de comandos. Las entradas pueden referenciar secretos con el campo "inputs" en lugar de escribir contraseñas en duro.

Cursor

Mediante CLI (espejo de la interfaz de Claude Code):

cursor mcp add taiga -e TAIGA_USERNAME=your_username -e TAIGA_PASSWORD=your_password -- npx -y mcp-taiga

O edita ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Activa el servidor en Configuración de Cursor → MCP e integraciones si no se activa inmediatamente.

Windsurf

Edita ~/.codeium/windsurf/mcp_config.json (o Configuración de Windsurf → Cascade → Servidores MCP → Gestionar MCP → Ver configuración en crudo) y actualiza el panel de MCP después:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Cline, Roo Code y Kilo Code

Las tres extensiones de VS Code usan un archivo de configuración JSON equivalente, editable desde el panel de Servidores MCP de cada extensión (haz clic en el icono del lápiz para abrir el archivo original):

Añade el servidor dentro del objeto "mcpServers" de nivel superior:

{
  "mcpServers": {
    "taiga": {
      "disabled": false,
      "timeout": 60,
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Cuando la extensión lo pida, aprueba el uso de las herramientas del servidor; la aprobación automática por herramienta se puede configurar en el mismo panel.

Continue.dev

Continue lee los servidores MCP desde bloques mcpServers: de su configuración o desde archivos YAML independientes en .continue/mcpServers/ (también acepta configuraciones JSON de Claude, Cursor o Cline colocadas sin cambios en ese directorio):

# ~/.continue/config.yaml (or .continue/mcpServers/taiga.yaml with
# name/version/schema metadata fields added)
name: Assistant
version: 1.0.0
schema: v1
mcpServers:
  - name: Taiga
    type: stdio
    command: npx
    args:
      - -y
      - mcp-taiga
    env:
      TAIGA_USERNAME: your_username
      TAIGA_PASSWORD: your_password

Las herramientas MCP están disponibles en modo agente.

Zed

Añade un servidor de contexto personalizado en settings.json (Zed → Abrir ajustes):

{
  "context_servers": {
    "taiga": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-taiga"],
        "env": {
          "TAIGA_USERNAME": "your_username",
          "TAIGA_PASSWORD": "your_password"
        }
      }
    }
  }
}

Entornos JetBrains

Abre Configuración → Herramientas → AI Assistant → MCP (o la página dedicada de ajustes de MCP en versiones recientes), haz clic en Añadir, elige Como JSON y pégalo:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Es necesario el plugin AI Assistant con la opción de MCP habilitada.

Gemini CLI

Edita ~/.gemini/settings.json y reinicia la CLI. Para cada uso de una herramienta se pedirá confirmación, a menos que las añadas a la lista de permitidas:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      },
      "includeTools": ["projects", "work", "sprints", "comments", "attachments", "wiki"]
    }
  }
}

Comprueba el registro con /mcp list dentro de la CLI.

Codex CLI

Añade una tabla de servidores en ~/.codex/config.toml:

[mcp_servers.taiga]
command = "npx"
args = ["-y", "mcp-taiga"]

[mcp_servers.taiga.env]
TAIGA_USERNAME = "your_username"
TAIGA_PASSWORD = "your_password"

Verifica con codex mcp list; las herramientas aparecen como taiga_* en las sesiones.

opencode

Añádelo a opencode.json (raíz del proyecto o ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "taiga": {
      "type": "local",
      "command": ["npx", "-y", "mcp-taiga"],
      "environment": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      },
      "enabled": true
    }
  }
}

Observa la clave singular environment y la forma de array para command, que difieren del esquema exclusivo de Claude.

Amp

Prefiere la CLI para los servidores de ámbito de usuario:

amp mcp add taiga -- npx -y mcp-taiga

O declara amp.mcpServers en ~/.config/amp/settings.json (las variantes de workspace .amp/settings.json requieren ejecutar antes amp mcp approve taiga):

{
  "amp.mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Pi

Pi lee su configuración MCP de Claude desde dos ámbitos: ~/.pi/agent/mcp.json (usuario) y .mcp.json o mcp.json en el directorio de trabajo (proyecto). Edita el archivo de usuario:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Los servidores remotos usan "url" más "transport": "http". Gestiona los servidores con /mcp dentro de una sesión (/mcp add, /mcp list, activar y desactivar por servidor).

Este repositorio incluye su propio .mcp.json, de modo que abrir pi dentro del checkout local toma la compilación local exterior automáticamente (no hacen falta credenciales ahí — el servidor de carga el .env del repo).

Oh My Pi

Aunque comparte el núcleo de agente con pi, omp tiene su propia raíz de configuración. Edita ~/.omp/agent/mcp.json:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Los servidores MCP se conectan cuando la sesión se crea — reinicia omp después de editarlo. Las herramientas aparecen como taiga_*; los ajustes a nivel de proyecto siguen el descubrimiento de pi (incluido el .mcp.json caute del repo).

Clientes remotos y web (transporte HTTP)

Define TAIGA_HTTP_PORT para exponer esas mismas seis herramientas sobre HTTP transmutable, sin lugar a stdio — útil para clientes que no puedan lanzar procesos locales, o para ejecutar una única instancia compartida:

TAIGA_HTTP_PORT=3000 npx -y mcp-taiga
# serves http://127.0.0.1:3000/mcp

Propiedades: modo sin sesión (sin cabeceras de sesión), vinculado a 127.0.0.1; se puede anular con TAIGA_HTTP_HOST (si usas una IP que no sea de bucle local, se imprime una advertencia por «HTTP de texto plano» en stderr), protección frente a rebind intrínsecamente habilitada para el host anunciado, JSON malformado rechazado con -32700, y cualquier método no POST en /mcp se contesta con 405.

Los clientes se conectan por URL en lugar de por comando:

{
  "mcpServers": {
    "taiga": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Equivalente en Continue.dev: type: streamable-http con url:; opencode: type: "remote" con url:. Como el proceso se lanza manualmente en lugar de serlo por el cliente, exporta TAIGA_USERNAME/TAIGA_PASSWORD en esa shell (o usa una unidad systemd, un contenedor, etc.).

Contenedores

El Dockerfile incluido en dos etapas utiliza Node 20 Alpine con un usuario node no root. La etapa de compilación parte del fuente TypeScript, y la etapa de runtime solo empaqueta la salida de dist/src compilada y las dependencias de producción.

Construye la imagen:

docker build -t mcp-taiga .

Rodéalo el contenedor conectado a la entrada/salida estándar:

docker run --rm -i --env-file .env mcp-taiga

Podman funciona por simple sustitución: remplaza docker por podman en los comandos de arriba.

Apunta una configuración de cliente MCP al runner del contenedor:

{
  "mcpServers": {
    "taiga": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/absolute/path/to/.env", "mcp-taiga"]
    }
  }
}

Para un despliegue mediante HTTP, publica el puerto en alternativa: docker run --rm -p 127.0.0.1:3000:3000 -e TAIGA_HTTP_PORT=3000 --env-file .env mcp-taiga y los clientes basados en URL deben dirigirse a http://127.0.0.1:3000/mcp.# Taiga MCP Server

Servidor de Model Context Protocol (MCP) para la gestión de proyectos de Taiga, escrito en TypeScript y construido sobre el Model Context Protocol SDK con transporte stdio (y un transporte HTTP transmisible opcional para clientes remotos y web). Conecta clientes LLM a instancias de Taiga para inspeccionar y gestionar proyectos, elementos de trabajo (incidencias, historias de usuario, tareas, épicas), sprints, comentarios, adjuntos y páginas wiki.

El servidor agrupa todas sus capacidades en 6 herramientas de despacho de operaciones, diseñadas para un consumo mínimo de tokens y respuestas de texto densas y legibles tanto para humanos como para modelos LLM.

Contenido

• Características · Requisitos y configuración · Inicio rápido · Checkout local · Transporte HTTP y clientes web · Contenedores

• Instalación: Claude Code · Claude Desktop · VS Code / Copilot · Cursor · Windsurf · Cline / Roo / Kilo · Continue.dev · Zed · JetBrains · Modelo · Codex · opencode · Amp · Pi · Oh My Pi

• Herramientas: Convenciones · Por qué seis herramientas · Referencia de herramientas: projects · work · sprints · comments · attachments · wiki

• Operaciones: Fiabilidad · Seguridad · FAQ · Solución de problemas · Desarrollo · Contribuciones · Historial de cambios · Licencia

Características

• Seis herramientas, veintiocho operaciones (pares de op) entre proyectos, elementos de trabajo, sprints, comentarios, adjuntos y páginas wiki; la carga útil completa de tools/list es de ~10,493 caracteres (~2,800 tokens).

• Identificadores legibles en todo: proyectos por ID o slug, elementos de rebaja por ID de base de datos o #reference, miembros por ID, nombre de usuario, nombre completo o "me"; estados, prioridades, severidades, tipos de incidencia y nombres de sprint se resuelven en el servidor.

• Texto denso: una línea por registro en las listas, vistas de detalle claras de tipo clave-valor; colecciones vacías se informan como datos, no como errores.

• Creación masiva de hasta 20 elementos de trabajo en una sola llamada; los borrados son deliberadamente de un solo objetivo.

• Guardabarros de fiabilidad: reintentos de límite de velocidad respetando Retry-After en segundos, tiempo de espera HTTP de 30 segundos, una caché de metadatos de 60 segundos y sin reintentos automáticos de errores 5xx (las peticiones mutadoras podrían haber llegado sin servidor).

• Seguridad de adjuntos: descargas ancladas al host, límite de 10 MB, protección ante sobreescritura y no se envía el token portador a los servidores de medios.

• **Video}; Doble transporte: stdio por defecto; HTTP de flujo a loopback cuando se define TAIGA_HTTP_PORT.

Requisitos y configuración

• Node.js >= 20.11

• Una cuenta de Taiga en taiga.io o unha instancia de Taiga autoalojada

• Estas tres variables de entorno:

Opcionales para el transporte:

Inicio rápido

La configuración más rápida es Claude Desktop con npx (no requiere instalación local):

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Todas las configuraciones de los distintos integradores que viene a continuación siguen este esquema; solo cambian la ruta del archivo y la sintaxis de su invocador.

Credenciales y .env: un checkout local carga automáticamente el .env de la raíz del repositorio (consulta .env.example). Una instalación por npx no: dotenv se resuelve relativo a la ubicación de instalación dentro de la caché de npm, así que las credenciales pasadas por npx SIEMPRE deben definirse en el bloque env de cada integración, como se muestra arriba.

Ejecutar desde un checkout local

git clone https://github.com/negoro26/mcp-taiga.git
cd mcp-taiga && npm ci && npm run build
cp .env.example .env   # fill in TAIGA_USERNAME / TAIGA_PASSWORD

Luego apunta cualquier integración al punto de entrada compilado en lugar de npx:

{
  "mcpServers": {
    "taiga": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-taiga/dist/src/index.js"]
    }
  }
}

Aquí no es necesario un bloque env: el servidor carga su .env de la raíz del repositorio. Este repositorio también incluye un .mcp.json ya preparado para que los agentes de código ejecutados en el checkout usen directamente la compilación local.

Instalación y configuración

Las siguientes configuraciones usan el paquete publicado en npm. Cada fragmento incluye credenciales de forma directa; reemplázalas por tus valores reales.

Claude Code

Ámbito de proyecto (guardado en el repo y compartido con tu equipo):

// .mcp.json at repository root
{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

O añade desde la CLI (ámbito de usuario con -s user, ámbito local por defecto):

claude mcp add taiga \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  -- npx -y mcp-taiga

Verifícalo con claude mcp list o /mcp con /mcp.

Claude Desktop

Edita el archivo de configuración — claude_desktop_config.json a través de Claude Desktop → Configuración → Developer → Editar configuración, situado en %APPDATA%\Claude\claude_desktop_config.json en Windows o en ~/Library/Application Support/Claude/claude_desktop_config.json en macOS — y reinicia la aplicación de escritorio:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

En Windows, usa cmd /c si la forma directa falla: "command": "cmd", "args": ["/c", "npx", "-y", "mcp-taiga"].

VS Code y GitHub Copilot

VS Code admite servidores MCP de forma nativa (1.99+); Copilot Chat los reconoce automáticamente.

// .vscode/mcp.json (workspace) or use Command Palette: "MCP: Add Server"
{
  "servers": {
    "taiga": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Inícialo desde la vista de Extensiones (mcp.json muestra un botón Iniciar) o ejecuta MCP: Listar Servidores en la Paleta de comandos. Los valores pueden referenciar secretos con el campo "inputs" en lugar de codificar contraseñas en el archivo.

Cursor

Mediante CLI (espejo de Claude Code):

cursor mcp add taiga -e TAIGA_USERNAME=your_username -e TAIGA_PASSWORD=your_password -- npx -y mcp-taiga

O edita ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Si no se activa automáticamente, actívalo en Cursor Settings → MCP & Integrations.

Windsurf

Edita ~/.codeium/windsurf/mcp_config.json (o Windsurf Settings → Cascade → MCP Servers → Manage MCPs → View Raw Config) y actualiza el panel MCP:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Cline, Roo Code y Kilo Code

Las tres extensiones de VS Code usan un archivo de configuración JSON equivalente; se edita desde el panel de servidores MCP de cada extensión (icono de lápiz para abrir el archivo en bruto):

Agrega el servidor dentro del objeto superior "mcpServers":

{
  "mcpServers": {
    "taiga": {
      "disabled": false,
      "timeout": 60,
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Confirma el uso de herramientas cuando la extensión te lo pregunte; la aprobación automática por herramienta se puede configurar en el mismo panel.

Continue.dev

Continue lee los servidores MCP de bloques mcpServers: de su configuración o desde archivos YAML independientes en .continue/mcpServers/ (también acepta configuraciones de Claude, Cursor o Clines en JSON sin cambios):

# ~/.continue/config.yaml (or .continue/mcpServers/taiga.yaml with
# name/version/schema metadata fields added)
name: Assistant
version: 1.0.0
schema: v1
mcpServers:
  - name: Taiga
    type: stdio
    command: npx
    args:
      - -y
      - mcp-taiga
    env:
      TAIGA_USERNAME: your_username
      TAIGA_PASSWORD: your_password

Las herramientas MCP están disponibles en el modo agente.

Zed

Añade un servidor de contexto personalizado en settings.json (zed: open settings):

{
  "context_servers": {
    "taiga": {
      "command": {
        "path": "npx",
        "args": ["-y", "mcp-taiga"],
        "env": {
          "TAIGA_USERNAME": "your_username",
          "TAIGA_PASSWORD": "your_password"
        }
      }
    }
  }
}

JetBrains IDEs

Abre Settings → Tools → AI Assistant → MCP (o la página de servidores MCP dedicada en versiones recientes), haz clic en Añadir, elige Como JSON y pega:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Requiere el plugin de AI Assistant con compatibilidad con MCP habilitada.

Gemini CLI

Edita ~/.gemini/settings.json e inicia de nuevo la CLI. Las herramientas exigen confirmación en cada llamada a menos que las añadas a la lista blanca:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      },
      "includeTools": ["projects", "work", "sprints", "comments", "attachments", "wiki"]
    }
  }
}

Comprueba el registro con /mcp list dentro de la CLI.

Codex CLI

Añade una tabla de servidores a ~/.codex/config.toml:

[mcp_servers.taiga]
command = "npx"
args = ["-y", "mcp-taiga"]

[mcp_servers.taiga.env]
TAIGA_USERNAME = "your_username"
TAIGA_PASSWORD = "your_password"

Verifíca con codex mcp list; dentro de los sesiones las herramientas se llaman taiga_*.

opencode

Agrega a opencode.json (raíz del proyecto o ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "taiga": {
      "type": "local",
      "command": ["npx", "-y", "mcp-taiga"],
      "environment": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      },
      "enabled": true
    }
  }
}

Observa que la clave es singular environment y command va en forma de array, a diferencia del esquema estilo Claude.

Amp

Es mejor usar la CLI para los servidores de ámbito de usuario:

amp mcp add taiga -- npx -y mcp-taiga

O define amp.mcpServers en ~/.config/amp/settings.json (las variantes de workspace .amp/settings.json requieren ejecutar amp mcp approve taiga antes):

{
  "amp.mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Pi

Pi lee su configuración MCP estilo Claude en dos ámbitos: ~/.pi/agent/mcp.json (usuario) y .mcp.json o mcp.json en el directorio de trabajo (proyecto). Edita el archivo de usuario:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Los servidores remotos usan "url" más "transport": "http". Gestiona los servidores con /mcp dentro de una sesión (/mcp add, /mcp list, habilitar/deshabilitar por servidor).

Este repositorio incluye su propia .mcp.json, así que iniciar Pi dentro de un checkout local usará automáticamente la compilación local (no necesita credenciales: el servidor lee su .env).

Oh My Pi

omp comparte el núcleo del agente con Pi pero tiene su propio directorio de configuración. Edita ~/.omp/agent/mcp.json:

{
  "mcpServers": {
    "taiga": {
      "command": "npx",
      "args": ["-y", "mcp-taiga"],
      "env": {
        "TAIGA_USERNAME": "your_username",
        "TAIGA_PASSWORD": "your_password"
      }
    }
  }
}

Los servidores MCP se conectan cuando se construye la sesión; reinicia omp después de editar. Las herramientas aparecen como taiga_*; las configuraciones de proyecto siguen la detección de Pi (incluido el .mcp.json versionado de este repo).

Clientes remotos y web (transporte HTTP)

Definiendo TAIGA_HTTP_PORT se exponen las mismas seis herramientas sobre HTTP Transmisible en lugar de stdio — útil para clientes que no pueden iniciar procesos locales, o para ejecutar una única instancia compartida:

TAIGA_HTTP_PORT=3000 npx -y mcp-taiga
# serves http://127.0.0.1:3000/mcp

Propiedades: modo sin estado (sin encabezados de sesión), escucha en 127.0.0.1 salvo que se sobreescriba TAIGA_HTTP_HOST (los non-loopback escriben una advertencia de HTTP en texto plano en stderr), protección de DNS rebinding activa para el host anunciado, JSON inválido rechazado con -32700, y los métodos no POST en /mcp devuelven 405.

Los clientes se conectan por URL, no por comando:

{
  "mcpServers": {
    "taiga": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Equivalente en Continue.dev: type: streamable-http con url:; en opencode: type: "remote" con url:. Como el proceso se lanza manualmente y no por el cliente, define TAIGA_USERNAME y TAIGA_PASSWORD en ese shell (o usa un unit de systemd, un contenedor, etc.).

Contenedores

El Dockerfile de dos etapas incluido usa Node 20 Alpine con un usuario node no root. La etapa de build compila el TypeScript y la etapa de runtime empaqueta solo de dist/src y las dependencias de producción.

Construye la imagen:

docker build -t mcp-taiga .

Ejecuta el contenedor adjuntado a la entrada/salida estándar:

docker run --rm -i --env-file .env mcp-taiga

Podman funciona con la misma sustitución directa: reemplaza docker por podman en los comandos anteriores.

Apunta tu configuración de cliente MCP al corredor del contenedor:

{
  "mcpServers": {
    "taiga": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "--env-file", "/absolute/path/to/.env", "mcp-taiga"]
    }
  }
}

Para un despliegue HTTP, publica el puerto en sustituto: docker run --rm -p 127.0.0.1:3000:3000 -e TAIGA_HTTP_PORT=3000 --env-file .env mcp-taiga, y apunta los clientes tipo URL a http://127.0.0.1:3000/mcp.

Deliberadamente no hay un archivo de compose. Un servidor MCP stdio debe lanzarse adjuntado directamente a los flujos stdin y stdout de su cliente, y termina cuando ese flujo stdin se cierra. Los supervisores de procesos o las configuraciones de compose que intentan mantener servicios en segundo plano de larga duración provocan bucles de reinicio infinitos y conflictos de nombres de contenedores.

Convenciones

• Projects: Los argumentos de proyecto aceptan un ID de proyecto numérico (p. ej. 19) o un slug (p. ej. "acme-web").

• Work Items: Los elementos de trabajo aceptan un ID numérico de base de datos (p. ej. 1888) o una referencia con prefijo de almohadilla (p. ej. "#70"). Una #reference requiere el argumento project para resolverse.

• People: Los argumentos de miembro aceptan un ID numérico de usuario, un nombre de usuario (p. ej. "jdoe"), un nombre completo (p. ej. "Jane Doe") o el literal "me".

• Taxonomies: Los estados, prioridades, gravedades, tipos de incidencia y nombres de sprint aceptan nombres legibles para humanos y se resuelven en IDs numéricos en el servidor.

• Multi-Assignee User Stories: Las historias de usuario de Taiga admiten múltiples asignados mediante assigned_users. El filtrado por assignee en work list type:story coincide con los coasignados, y los listados muestran todos los asignados y no solo el principal.

• Dense Text Results: Los resultados se muestran como texto plano, formateado con una línea densa por registro o bloques limpios de clave-valor para las vistas de detalle. Ningún consumidor lee structuredContent, por lo que los resultados son solo texto. Una colección vacía se informa como <items> in <project>: 0 en lugar de un error.

• Full Collections: Los endpoints de listado devuelven colecciones completas porque el cliente envía la cabecera de solicitud x-disable-pagination: true, eliminando así los viajes de ida y vuelta de varias páginas.

Por qué seis herramientas

La proliferación de herramientas de propósito único provoca una sobrecarga considerable en la ventana de contexto antes de invocar cualquier herramienta. Consolidar la funcionalidad en seis herramientas de dominio operadas por despacho (op) mantiene la carga útil de tools/list en unas 10.493 caracteres (~2.800 tokens).

Los esquemas de salida se omiten deliberadamente en los registros de herramientas: los puentes de clientes MCP concatenan el contenido de texto e ignoran outputSchema y structuredContent, por lo que omitir los esquemas de salida elimina la sobrecarga innecesaria de tokens al inicio de la sesión.

Referencia de tool

El servidor expone 6 herramientas que cubren 28 pares de operaciones.

1. projects

Sirve para listar o inspeccionar proyectos de Taiga y verificar credenciales.

2. work

Gestion de incidencias, historias de usuario, tareas y épicas (type: issue, story, task, epic).

3. sprints

Gestión de sprints (hitos) e inspección de las estadísticas de progreso.

La eliminación de sprints no está expuesta intencionadamente: quitar un hito desvincula todas las historias y tareas de ese hito, lo que constituye una edición de todo el tablero que pertenece a la interfaz de Taiga.

4. comments

Operaciones para listar, añadir, editar o eliminar comentarios en elementos de trabajo y páginas wiki (type: issue, story, task, epic, wiki).

5. attachments

Operaciones para gestionar archivos adjuntos en elementos de trabajo y páginas wiki (type: issue, story, task, epic, wiki).

6. wiki

Gestión de páginas wiki y suscripciones a páginas wiki dentro de un proyecto.

Fiabilidad y sesgo de seguridad

• Límite de tasa (429): El servidor reintenta las respuestas HTTP 429 como máximo dos veces, respetando el encabezado Retry-After del servidor. Si la espera requerida supera el tope de 5 segundos (MAX_THROTTLE_WAIT_MS), lanza de inmediato un mensaje de reintento en lugar de dormir.

• Errores 5xx nunca reintentados: Las respuestas 5xx no se reintentan nunca automáticamente porque las solicitudes de mutación (como POST) pueden haber sido aplicadas ya en el servidor; repetirlas puede crear registros duplicados.

• Caché de metadatos: Los metadatos del proyecto (búsquedas de slug, membresías de usuario y listas de taxonomía para estados, prioridades, severidades y tipos de incidencia) se guardan en caché durante 60 segundos (METADATA_TTL_MS) mediante getMetadata. Los elementos de trabajo, comentarios y adjuntos nunca se guardan en caché.

• Tiempos de espera: Las solicitudes HTTP aplican un tiempo de espera de 30 segundos (REQUEST_TIMEOUT_MS).

• Aplicación de HTTPS: El servidor emite una advertencia a stderr si TAIGA_API_URL usa HTTP sin cifrado hacia un host que no sea loopback.

• Descargas de adjuntos restringidas: Las descargas de adjuntos se limitan estrictamente al hostname de Taiga configurado, sin permitir redirecciones (maxRedirects: 0), y con un límite de tamaño máximo de archivo de 10 MB (MAX_ATTACHMENT_BYTES). La solicitud de descarga no envía el bearer token de Taiga a los hosts de medios.

• Protección contra sobrescritura de archivos: La descarga de adjuntos con savePath se niega a sobrescribir un archivo local existente.

• Eliminaciones de un solo objetivo: Las operaciones de eliminación aceptan exactamente un objetivo a la vez. Las operaciones por lotes son solo de creación (hasta 20 elementos), lo que evita eliminaciones accidentales en todo el tablero.

Consideraciones de seguridad

• Las credenciales viajan mediante variables de entorno o archivos de configuración del harness, nunca mediante argumentos de línea de comandos (que se filtran a través de las listas de procesos) y nunca desde el repositorio. Mantén los archivos de configuración del harness que contengan contraseñas incrustadas fuera del control de versiones; .gitignore ya excluye .env* excepto .env.example.

• El transporte HTTP opcional se vincula a loopback por defecto y activa la protección contra el rebinding de DNS; vincular a una dirección enrutable imprime una advertencia porque el tráfico no está cifrado.

• Las descargas de adjuntos nunca transportan un bearer token fuera del hostname de Taiga, rechazan redirecciones, limitan el tamaño del archivo y se niegan a sobrescribir archivos existentes.

• Las superficies de eliminación son de un solo objetivo por diseño; no hay eliminación en lote.

FAQ

¿Qué clientes MCP pueden usarlo? Cualquier cliente que hable stdio MCP — la guía de instalación cubre diecisiete de ellos con configuraciones listas para copiar y pegar — además de los clientes basados en URL a través del transporte HTTP.

¿Funciona con Taiga autoalojado? Sí. Define TAIGA_API_URL en tu instancia incluyendo el sufijo /api/v1 (por ejemplo, https://taiga.example.com/api/v1). Todo lo demás se comporta igual; si las solicitudes devuelven 404, consulta Solución de problemas.

¿Puedo conectar más de una cuenta o instancia de Taiga? No dentro de un proceso de servidor: contiene exactamente un conjunto de credenciales, leído del entorno al arrancar. Registra entradas adicionales en mcpServers (por ejemplo, "taiga-work") con sus propios valores de env; cada una se convierte en un espacio de nombres de herramientas independiente, como mcp__taiga-work__work.

¿A dónde va mi contraseña? Desde tu bloque de entorno a la memoria, y desde ahí solo al host de Taiga configurado durante el intercambio de login; nunca a líneas com conos (que se filtran en listas de procesos), registros, resultados de herramientas ni hosts de descarga de adjuntos. Ver Consideraciones de seguridad.

¿Es de solo lectura? No: crea, actualiza, enlaza/desenlaza y elimina elementos de trabajo, sprints, comentarios, adjuntos y páginas wiki. La eliminación de sprints y por lotes está deliberadamente ausente — consulte Fiabilidad y seguridad.

¿Por qué solo seis herramientas cuando otros servidores MCP exponen docenas? Economía de la ventana de contexto: cada definición de herramienta se paga en cada inicio de sesión. Ver Por qué seis herramientas.

Algo se rompió — ¿por dónde empiezo? Solución de problemas cubre los modos de fallo más comunes; más allá de eso, abre un issue de GitHub con la llamada a la herramienta que falla y la salida de stderr del servidor.

Solución de problemas

• Fallos de autenticación — ejecuta la herramienta projects con op: whoami; informa exactamente qué intercambio de credenciales falló. Comprueba si hay espacios en blanco en los valores de entorno y que la cuenta funciona en la interfaz web de Taiga.

• La instancia autoalojada devuelve 404 — TAIGA_API_URL debe incluir la ruta /api/v1, por ejemplo, https://taiga.example.com/api/v1.

• El servidor arranca pero el cliente npx no ve herramientas — confirma que Node.js >= 20.11 se ejecuta en el entorno del harness; los lanzadores con interfaz gráfica suelen heredar un PATH distinto al de tu shell.

• Credenciales ignoradas con npx — las instalaciones de npx no cargan un .env; pon las credenciales en el bloque env del harness (solo los checkouts locales cargan .env automáticamente).

• Conflictos de puerto en modo HTTP — otro proceso tiene el puerto ocupado; elige otro TAIGA_HTTP_PORT. El servidor sale con código de error no nulo y un error de escucha, en lugar de reintentar.

• Conjuntos de resultados vacíos — los listados muestran <items> in <project>: 0; esa es una respuesta correcta, no un error.

• Cursor/Windsurf en server presente pero inactivo — activa el interruptor de servidor habilitado en el panel correspondiente después de editar los archivos de configuración; ambos guardan el estado en caché hasta que se actualizan.

Desarrollo

Estructura de archivos

src/index.ts            # Entrypoint: createServer() factory, stdio vs HTTP transport selection
src/http.ts             # Streamable HTTP transport (node:http, stateless, DNS-rebinding protected)
src/api.ts              # Authenticated axios transport, generic HTTP helpers (get, post, patch, del), token management, retry policy, metadata cache
src/taiga.ts            # Domain helpers: resolution (projects, items, members, taxonomies, sprints) and optimistic concurrency patch
src/types.ts            # Taiga payload interfaces, tool definitions, and type contracts
src/format.ts           # Dense pipe-separated single-line renderers and detail views
src/utils.ts            # MCP response builders (createSuccessResponse, createErrorResponse, guard) and formatting helpers
src/constants.ts        # Endpoints, limits (batch size, attachment size), status labels, error messages
src/tools/index.ts      # Tool registry aggregating all tools and registering with McpServer
src/tools/projects.ts   # projects tool (list, get, whoami)
src/tools/work.ts       # work tool (list, get, create, update, link, unlink, delete across issues, stories, tasks, epics)
src/tools/sprints.ts    # sprints tool (list, get, create, stats)
src/tools/comments.ts   # comments tool (list, add, edit, delete)
src/tools/attachments.ts # attachments tool (list, upload, download, delete)
src/tools/wiki.ts       # wiki tool (list, get, create, update, delete, watch)
test/unitTest.ts        # Offline unit tests for pure helpers, formatting functions, response builders, and tool invariants
test/protocolTest.ts    # Protocol tests verifying MCP stdio handshake, server capabilities, tool count, and tools/list budget
test/httpTest.ts        # Transport tests verifying the streamable HTTP endpoint: handshake, tools/list, routing rejections
test/apiContractTest.ts # Contract tests driving every tool op against an in-process mock Taiga HTTP server, asserting outgoing HTTP requests
test/integration.ts     # Live integration smoke test against a real Taiga instance (read-only, skips without credentials)

Scripts de NPM

• npm run build: Compila TypeScript desde src/ y test/ a dist/ mediante tsc.

• npm run check: Ejecuta comprobación de tipos en código TypeScript sin generación de resultados (tsc --noEmit).

• npm run lint: Ejecuta oxlint sobre src/ y test/.

• npm start: Ejecuta el servidor compilado (node dist/src/index.js).

• npm test: Compila y ejecuta las suites de prueba unitarias, de protocolo(x, contrato y de transporte HTTP en secuencia.

• npm run test:unit: Compila y ejecuta pruebas offline unitarias.

• npm run test:protocol: Compila y ejecuta las pruebas de protocolo MCP sobre stdio.

• npm run test:http: Compila y ejecuta las pruebas de transporte HTTP streamable.

• npm run test:contract: Compila y ejecuta las pruebas de contrato de API contra el servidor de simulación de Taiga.

• npm run test:integration: Compila y ejecuta pruebas de integración en vivo contra una instancia real.

• npm run prepublishOnly: Ejecuta type-check, lint y suite completA de pruebas antes de publicar.

Conjuntos de test

1. Pruebas unitarias (test/unitTest.ts): Pruebas unitarias sin conexión que verifican funciones de formato puro, builders de respuesta, utilidades de resolución de identificadores e invariantes de definición de herramientas sin llamadas de red ni credenciales.

2. Pruebas de protocolo (test/protocolTest.ts): Pruebas de protocolo que verifican el handshake real de MCP stdio, la versión y capacidades del servidor, los esquemas de herramientas y el presupuesto de caracteres de tools/list contra un proceso servidor lanzado.

3. Pruebas HTTP (test/httpTest.ts): Lanza el servidor compilado con TAIGA_HTTP_PORT y verifica el handshake real de HTTP streamable, eco de versión de protocolo, comportamiento sin estado, contenido de tools/list y rechazos de ruta 400/404/405 sobre localhost.

4. Pruebas de contrato (test/apiContractTest.ts): Garantizan que cada herramienta y op envía las solicitudes HTTP de salida esperadas (método, endpoint, parámetros de query, cabeceras y carga) y procesa las respuestas contra un servidor de simulación HTTP Taiga dentro del mismo proceso.

5. Pruebas de integración (test/integration.ts): Pruebas smoke de integración en vivo que verifican operaciones de solo lectura contra una instancia de Taiga real sobre stdio (omitidas si las credenciales no están configuradas).

Contribuidores

Las pull requests se dirigen a dev; ve a CONTRIBUTING.md para el modelo de ramas (dev → staging → main), convenciones de commits y proceso de publicación.

Historial de cambios

Véase CHANGELOG.md.

Licencia

MIT