mcp-linear

Servidor MCP que expone operaciones de incidencias de Linear. Independiente: sin dependencia del MCP de Linear integrado en Claude.

Las incidencias se identifican por su identificador humano (GOV-123). Los estados, equipos, etiquetas y asignados se indican por nombre; el servidor los resuelve a UUID de Linear y devuelve un error con las opciones válidas cuando un nombre no coincide.

Herramientas

Configuración

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env
# Edit .env — set LINEAR_API_KEY

Obtén una clave de API: Linear → Configuración → Seguridad y acceso → Claves de API personales. Las operaciones de escritura necesitan una clave con acceso de escritura.

Añadir a Claude Code

{
  "mcpServers": {
    "linear": {
      "command": "/Users/piuschungath/Workspace/mcp-linear/.venv/bin/mcp-linear",
      "env": { "LINEAR_API_KEY": "lin_api_..." }
    }
  }
}

Pruebas

.venv/bin/pytest

Todo el HTTP se simula con respx. No se necesita clave de API ni acceso a la red.

Con mcp-pr-assistant

Los dos servidores se combinan sin importarse entre sí: obtén un ticket con get_issue, pasa sus campos a create_pr_from_ticket y luego publica la URL del PR de vuelta con add_comment.

Verificación del esquema

Los nombres de campos GraphQL en src/mcp_linear/queries.py se verificaron contra la API de Linear en vivo el 2026-08-21, ejecutando las cadenas de consulta reales de las herramientas (no copias) contra un espacio de trabajo real.

Verificado correcto:

• el comparador de número de incidencia Float!

• etiquetas de ámbito de equipo mediante team { labels }

• la conexión raíz issueLabels

• viewer.assignedIssues(orderBy: updatedAt)

• todos los campos que envían las tres mutaciones: IssueCreateInput, IssueUpdateInput y CommentCreateInput aceptan teamId, title, description, stateId, assigneeId, priority, labelIds, issueId y body tal como se usan.

Se encontró y corrigió una divergencia:

• Búsqueda de texto completo. issueSearch rechaza su argumento query como obsoleto. La búsqueda ahora usa searchIssues(term: ...), que devuelve IssueSearchPayload cuyos nodos son IssueSearchResult, no Issue, por lo que no puede expandir el fragmento IssueFields. queries.py declara un segundo fragmento, SearchFields, con la misma selección en ese tipo. La introspección confirmó que IssueSearchResult contiene todos los campos que selecciona IssueFields. Si cambias un fragmento, cambia el otro.

Una cosa sigue sin confirmar:

• Etiquetas del espacio de trabajo. La conexión raíz issueLabels se resuelve, pero no se estableció si devuelve solo etiquetas de todo el espacio de trabajo o también etiquetas de ámbito de equipo que pertenecen a otros equipos. La resolución de etiquetas consulta primero las etiquetas propias del equipo, por lo que una etiqueta de equipo siempre gana sobre una del espacio de trabajo con el mismo nombre.

Para volver a verificar después de un cambio de esquema de Linear:

LINEAR_API_KEY=lin_api_... .venv/bin/python scripts/probe_schema.py <team-key> <issue-number> <issue-uuid>

Toma una clave de equipo, un número de incidencia existente en ese equipo y el UUID de esa incidencia (y solicita una vez, de forma interactiva, un UUID de equipo impreso por su primera sonda). La sonda es de solo lectura: las mutaciones se verifican inspeccionando sus tipos de entrada, nunca escribiendo en tu rastreador.

Notas

• Las claves de API personales de Linear se envían como Authorization: <key> sin prefijo Bearer.

• Linear informa la mayoría de los fallos como HTTP 200 con una matriz errors de nivel superior, por lo que el cliente verifica el cuerpo de la respuesta en lugar del código de estado.

• Los metadatos de equipos, estados, etiquetas y usuarios se almacenan en caché durante la vida del proceso del servidor. Reinicia el servidor después de cambiar los estados de flujo de trabajo o las etiquetas de un equipo.