Linear

Consulta y busca incidencias en tu espacio de trabajo de Linear.

Documentación

Servidor MCP de Linear

Una implementación de servidor del Model Context Protocol (MCP) que proporciona acceso al sistema de seguimiento de incidencias de Linear a través de una interfaz estandarizada.

Características

Crear nuevas incidencias y subincidencias con soporte de etiquetas
Recuperar la lista de proyectos de Linear
Recuperar las actualizaciones de proyectos
Crear una nueva actualización de proyecto con estado de salud
Actualizar incidencias existentes con modificación completa de campos
Eliminar incidencias con validación
Autoasignar incidencias usando la palabra clave 'me'
Búsqueda avanzada con las potentes capacidades de filtrado de Linear
Filtrar incidencias por ciclo (actual, siguiente, anterior o ciclo específico por UUID o número)
Añadir comentarios a incidencias con soporte de Markdown
Consultar incidencias de Linear por ID o clave con relaciones opcionales
Buscar incidencias usando consultas personalizadas con metadatos mejorados
Operaciones con seguridad de tipos usando el SDK oficial de Linear
Manejo integral de errores
Manejo de límites de tasa
Transformación limpia de datos
Seguimiento de relaciones padre/hijo con herencia de equipo
Gestión y sincronización de etiquetas

Requisitos previos

Bun runtime (v1.0.0 o superior)
Cuenta de Linear con acceso a la API

Variables de entorno

LINEAR_API_KEY=your_api_key  # Your Linear API token

Instalación y configuración

1. Clonar el repositorio:

git clone [repository-url]
cd linear-mcp

2. Instalar dependencias y compilar:

bun install
bun run build

3. Configurar el servidor MCP:

Edita el archivo de configuración correspondiente:

macOS:

Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Claude Desktop: lamentablemente aún no existe

Añade la siguiente configuración bajo el objeto mcpServers:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_api_key"
      }
    }
  }
}

4. Reiniciar el servidor MCP.

Dentro de la configuración MCP de Cline, reinicia el servidor MCP. Reinicia Claude Desktop para cargar el nuevo servidor MCP.

Desarrollo

Ejecutar el servidor de desarrollo:

bun run dev

Compilar el proyecto:

bun run build

Herramientas MCP disponibles

Para ejemplos detallados de uso de todas las herramientas, consulta USAGE.md.

create_issue

Crear una nueva incidencia o subincidencia de Linear.

Esquema de entrada:

{
  "teamId": "string",     
  "title": "string",      
  "description": "string",
  "parentId": "string",   
  "status": "string",
  "priority": "number",   
  "assigneeId": "string | 'me'",
  "labelIds": ["string"]  
}

update_issue

Actualizar una incidencia existente de Linear.

Esquema de entrada:

{
  "issueId": "string",    
  "title": "string",
  "description": "string",
  "status": "string",     // Expects status NAME (e.g., "In Progress"). Must be valid for the issue's team.
  "priority": "number",   // Expects 0 (None) to 4 (Low).
  "assigneeId": "string | 'me'",
  "labelIds": ["string"],
  "cycleId": "string"
}

get_issue

Obtener información detallada sobre una incidencia específica de Linear con relaciones opcionales.

Esquema de entrada:

{
  "issueId": "string",
  "includeRelationships": "boolean"  
}

search_issues

Buscar incidencias de Linear usando una cadena de consulta y filtros avanzados. Soporta las potentes capacidades de filtrado de Linear.

Esquema de entrada:

{
  "query": "string",
  "includeRelationships": "boolean",
  "filter": {
    "title": { "contains": "string", "eq": "string", ... },
    "description": { "contains": "string", "eq": "string", ... },
    "priority": { "gte": "number", "lt": "number", ... },
    "estimate": { "eq": "number", "in": ["number"], ... },
    "dueDate": { "lt": "string", "gt": "string", ... },
    "createdAt": { "gt": "P2W", "lt": "2024-01-01", ... },
    "updatedAt": { "gt": "P1M", ... },
    "completedAt": { "null": true, ... },
    "assignee": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "creator": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "team": { "id": { "eq": "string" }, "key": { "eq": "string" } },
    "state": { "type": { "eq": "started" }, "name": { "eq": "string" } },
    "labels": { "name": { "in": ["string"] }, "every": { "name": { "eq": "string" } } },
    "project": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "and": [{ /* filters */ }],
    "or": [{ /* filters */ }],
    "assignedTo": "string | 'me'",
    "createdBy": "string | 'me'"
  },
  "projectId": "string",
  "projectName": "string"
}

Comparadores soportados:

Campos de texto: eq, neq, in, nin, contains, startsWith, endsWith (más variantes que no distinguen entre mayúsculas y minúsculas)
Campos numéricos: eq, neq, lt, lte, gt, gte, in, nin
Campos de fecha: eq, neq, lt, lte, gt, gte (soporta duraciones ISO 8601)

get_teams

Obtener una lista de equipos de Linear con filtrado opcional por nombre/clave.

Esquema de entrada:

{
  "nameFilter": "string"  
}

delete_issue

Eliminar una incidencia existente de Linear.

Esquema de entrada:

{
  "issueId": "string"
}

create_comment

Crear un nuevo comentario en una incidencia de Linear.

Esquema de entrada:

{
  "issueId": "string",
  "body": "string"
}

get_projects

Obtener una lista de proyectos de Linear con filtrado opcional por nombre y paginación.

Esquema de entrada:

{
  "nameFilter": "string",
  "includeArchived": "boolean",
  "first": "number",
  "after": "string"
}

get_project_updates

Obtener actualizaciones de proyecto para un ID de proyecto dado con parámetros de filtrado opcionales.

Esquema de entrada:

{
  "projectId": "string",
  "includeArchived": "boolean",
  "first": "number",
  "after": "string",
  "createdAfter": "string",
  "createdBefore": "string",
  "userId": "string | 'me'",
  "health": "string"
}

create_project_update

Crear una nueva actualización para un proyecto de Linear.

Esquema de entrada:

{
  "projectId": "string",
  "body": "string",
  "health": "onTrack | atRisk | offTrack",
  "isDiffHidden": "boolean"
}

Detalles técnicos

Construido con TypeScript en modo estricto
Utiliza el SDK oficial de Linear (@linear/sdk)
Utiliza el SDK de MCP (@modelcontextprotocol/sdk 1.4.0)
Autenticación mediante tokens de API
Manejo integral de errores
Consideraciones de límites de tasa
Runtime de Bun para mejor rendimiento
Módulos ESM en todo el proyecto
Sistema de compilación Vite
Operaciones con seguridad de tipos
Funciones de limpieza de datos:
- Extracción de menciones de incidencias (formato ABC-123)
- Extracción de menciones de usuarios (formato @usuario)
- Limpieza de contenido Markdown
- Optimización de contenido para contexto de IA
Soporte de autoasignación:
- Resolución automática del usuario actual
- Soporte de la palabra clave 'me' en operaciones de creación/actualización
- Caché eficiente de IDs de usuario
Capacidades de búsqueda avanzada:
- Filtrado integral con la API de Linear
- Soporte para todos los comparadores de campos
- Filtrado de relaciones
- Operadores lógicos (y, o)
- Filtrado de fechas relativas
- Filtrado por asignado/creador (incluido uno mismo)
- Soporte para IDs de usuario específicos
- Filtrado de proyectos por ID o nombre
- Optimización eficiente de consultas
Funciones de gestión de proyectos:
- Listado de proyectos con filtrado y paginación
- Creación de actualizaciones de proyecto con seguimiento de estado de salud
- Recuperación de actualizaciones de proyecto con opciones de filtrado

Manejo de errores

El servidor implementa una estrategia integral de manejo de errores:

Detección de errores de red y mensajes apropiados
Manejo de códigos de estado HTTP
Mensajes de error detallados con códigos de estado
Registro de detalles de errores en la consola
Validación de entrada para todos los parámetros
Validación y sincronización de etiquetas
Propagación segura de errores a través del protocolo MCP
Detección y manejo de límites de tasa
Manejo de errores de autenticación
Manejo de consultas no válidas
Validación de herencia de equipo para subincidencias
Validación de resolución de usuarios
Validación de filtros de búsqueda

LICENCIA

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