youtrack-mcp

Un servidor MCP para YouTrack, construido con TypeScript y Bun. Funciona con cualquier instancia de YouTrack (Cloud o autoalojada) — tú proporcionas la URL base y un token de API, nada está codificado.

Configuración

Necesitas un token permanente de YouTrack: en YouTrack, ve a tu perfil → Account Security → New token....

Establece dos variables de entorno:

• YOUTRACK_BASE_URL — la URL base de la API REST de tu instancia, p. ej. https://mycompany.youtrack.cloud/api o https://youtrack.mycompany.com/api para instalaciones autoalojadas.

• YOUTRACK_TOKEN — el token permanente.

Instala las dependencias con Bun:

bun install

Ejecución directa

YOUTRACK_BASE_URL=https://mycompany.youtrack.cloud/api YOUTRACK_TOKEN=perm:xxxx bun run src/index.ts

Configurar en un cliente MCP

Por ejemplo, en el mcp.json de Claude Code / Claude Desktop:

{
  "mcpServers": {
    "youtrack": {
      "command": "bun",
      "args": ["run", "/path/to/youtrack-mcp/src/index.ts"],
      "env": {
        "YOUTRACK_BASE_URL": "https://mycompany.youtrack.cloud/api",
        "YOUTRACK_TOKEN": "perm:xxxx"
      }
    }
  }
}

Related MCP server: YouTrack MCP

Herramientas

Las herramientas se agrupan por recurso y comparten un argumento fields (la sintaxis de respuesta parcial de YouTrack) con un valor predeterminado razonable, por lo que solo necesitas especificarlo cuando quieras recibir más o menos datos.

• Issues — list_issues (búsqueda), get_issue, create_issue, update_issue, delete_issue, execute_command (aplica cualquier comando de YouTrack — estado, asignado, prioridad, enlaces, etiquetas, sprint, etc. mediante su sintaxis de consulta natural, p. ej. "State Fixed assignee John.Doe")

• Comentarios — list_issue_comments, add_issue_comment, update_issue_comment, delete_issue_comment

• Enlaces — list_issue_links, list_issue_link_types

• Etiquetas — list_tags, create_tag, list_issue_tags, add_issue_tag, remove_issue_tag

• Seguimiento de tiempo — list_issue_work_items, add_issue_work_item, update_issue_work_item, delete_issue_work_item, list_work_items

• Proyectos — list_projects, get_project, create_project, update_project, list_project_custom_fields

• Usuarios y grupos — get_current_user, list_users, get_user, list_groups

• Base de conocimiento — list_articles, get_article, create_article, update_article, delete_article

• Tableros ágiles — list_agile_boards, get_agile_board, list_sprints, get_sprint

• Búsquedas guardadas — list_saved_queries

• Vía de escape — youtrack_raw_request llama directamente a cualquier endpoint de la API REST de YouTrack (método, ruta, consulta, cuerpo), para la larga cola de endpoints de administración/configuración no cubiertos por una herramienta dedicada.

Diseño

• src/youtrack/client.ts — el único lugar que habla HTTP: cabecera de autenticación, construcción de URL/consulta, JSON y manejo de errores. Todas las herramientas pasan por él.

• src/youtrack/fields.ts — valores predeterminados de fields por entidad, tomados de los valores predeterminados de OpenAPI de YouTrack.

• src/youtrack/params.ts — fragmentos de esquema Zod compartidos (fields, paginación, IDs) reutilizados en todas las herramientas.

• src/tool.ts — defineTool + registerTools, de modo que cada archivo de herramienta solo declara un nombre/descripción/esquema/manejador y el envoltorio de respuesta/error de MCP ocurre en un solo lugar.

• src/youtrack/tools/*.ts — un archivo por recurso, cada herramienta con unas pocas líneas construidas sobre las piezas compartidas anteriores.

Desarrollo

bun run typecheck   # tsc --noEmit
bun run dev         # run with --watch