mcp-linear

MCP-Server, der Linear-Issue-Operationen bereitstellt. Eigenständig — keine Abhängigkeit vom integrierten Claude-Linear-MCP.

Issues werden über ihre menschenlesbare Kennung (GOV-123) angesprochen. Status, Teams, Labels und Bearbeiter werden namentlich angegeben; der Server löst sie in Linear-UUIDs auf und gibt bei fehlender Übereinstimmung einen Fehler mit den gültigen Optionen zurück.

Tools

Setup

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

API-Schlüssel erhalten: Linear → Settings → Security & access → Personal API keys. Für Schreiboperationen wird ein Schlüssel mit Schreibzugriff benötigt.

Zu Claude Code hinzufügen

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

Tests

.venv/bin/pytest

Der gesamte HTTP-Verkehr wird mit respx gemockt. Es werden weder ein API-Schlüssel noch Netzwerkzugriff benötigt.

Mit mcp-pr-assistant

Die beiden Server lassen sich kombinieren, ohne sich gegenseitig zu importieren: Ein Ticket mit get_issue abrufen, seine Felder an create_pr_from_ticket übergeben und anschließend die PR-URL mit add_comment zurückposten.

Schema-Verifizierung

Die GraphQL-Feldnamen in src/mcp_linear/queries.py wurden am 2026-08-21 gegen die Live-Linear-API verifiziert, indem die tatsächlichen Query-Strings der Tools (nicht Kopien davon) gegen einen echten Workspace ausgeführt wurden.

Als korrekt verifiziert:

• der Float!-Vergleichsoperator für Issue-Nummern

• teambezogene Labels über team { labels }

• die Root-Verbindung issueLabels

• viewer.assignedIssues(orderBy: updatedAt)

• jedes Feld, das die drei Mutationen senden — IssueCreateInput, IssueUpdateInput und CommentCreateInput akzeptieren alle teamId, title, description, stateId, assigneeId, priority, labelIds, issueId und body wie verwendet

Eine Abweichung wurde gefunden und behoben:

• Volltextsuche. issueSearch lehnt sein query-Argument als veraltet ab. Die Suche verwendet nun searchIssues(term: ...), das IssueSearchPayload zurückgibt, dessen Knoten IssueSearchResult sind, nicht Issue — daher kann es das IssueFields-Fragment nicht einbetten. queries.py deklariert ein zweites Fragment, SearchFields, mit derselben Auswahl auf diesem Typ. Die Introspection bestätigte, dass IssueSearchResult jedes Feld enthält, das IssueFields auswählt. Wenn Sie ein Fragment ändern, ändern Sie auch das andere.

Eine Sache bleibt unbestätigt:

• Workspace-Labels. Die Root-Verbindung issueLabels wird aufgelöst, aber ob sie nur workspaceweite Labels zurückgibt — oder auch teambezogene Labels anderer Teams — wurde nicht festgestellt. Bei der Label-Auflösung werden zuerst die eigenen Labels eines Teams berücksichtigt, sodass ein Team-Label immer über einem gleichnamigen Workspace-Label gewinnt.

Zur erneuten Verifizierung nach einer Linear-Schemaänderung:

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

Er benötigt einen Team-Schlüssel, eine bestehende Issue-Nummer in diesem Team und die UUID dieses Issues (und fragt einmalig interaktiv nach einer Team-UUID, die sein erster Testlauf ausgibt). Der Testlauf ist schreibgeschützt: Die Mutationen werden durch Introspection ihrer Eingabetypen geprüft, niemals durch Schreiben in Ihren Tracker.

Hinweise

• Persönliche Linear-API-Schlüssel werden als Authorization: <key> ohne Bearer-Präfix gesendet.

• Linear meldet die meisten Fehler als HTTP 200 mit einem errors-Array auf oberster Ebene, daher prüft der Client den Antworttext statt des Statuscodes.

• Team-, Status-, Label- und Benutzermetadaten werden für die Lebensdauer des Serverprozesses zwischengespeichert. Starten Sie den Server neu, nachdem Sie die Workflow-Status oder Labels eines Teams geändert haben.