mcp-linear

MCP server exposing Linear issue operations. Standalone — no dependency on the built-in Claude Linear MCP.

Issues are addressed by their human identifier (GOV-123). States, teams, labels, and assignees are given by name; the server resolves them to Linear UUIDs and returns an error listing valid options when a name does not match.

Tools

Tool	Description
get_issue	Fetch an issue by identifier
list_my_issues	Issues assigned to the API key's owner
search_issues	Full-text search with team/state/assignee filters
create_issue	Create an issue on a team
update_issue	Update fields on an existing issue
get_comments	Comments on an issue
add_comment	Post a comment
list_teams	Team keys and names
list_states	Workflow states for a team
list_labels	Labels on a team plus workspace labels (team optional)
list_users	Active users

Setup

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

Get an API key: Linear → Settings → Security & access → Personal API keys. Write operations need a key with write access.

Add to Claude Code

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

Tests

.venv/bin/pytest

All HTTP is mocked with respx. No API key and no network access are needed.

With mcp-pr-assistant

The two servers compose without importing each other: fetch a ticket with get_issue, pass its fields to create_pr_from_ticket, then post the PR URL back with add_comment.

Schema verification

The GraphQL field names in src/mcp_linear/queries.py were verified against the live Linear API on 2026-08-21, by running the tools' actual query strings (not copies of them) against a real workspace.

Verified correct:

• the Float! issue-number comparator
• team-scoped labels via team { labels }
• the root issueLabels connection
• viewer.assignedIssues(orderBy: updatedAt)
• every field the three mutations send — IssueCreateInput, IssueUpdateInput and CommentCreateInput all accept teamId, title, description, stateId, assigneeId, priority, labelIds, issueId and body as used

One divergence was found and fixed:

• Full-text search. issueSearch rejects its query argument as deprecated. Search now uses searchIssues(term: ...), which returns IssueSearchPayload whose nodes are IssueSearchResult, not Issue — so it cannot spread the IssueFields fragment. queries.py declares a second fragment, SearchFields, with the identical selection on that type. Introspection confirmed IssueSearchResult carries every field IssueFields selects. If you change one fragment, change the other.

One thing remains unconfirmed:

• Workspace labels. The root issueLabels connection resolves, but whether it returns workspace-wide labels only — or also team-scoped labels belonging to other teams — was not established. Label resolution consults a team's own labels first, so a team label always wins over a same-named workspace one.

To re-verify after a Linear schema change:

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

It takes a team key, an existing issue number on that team, and that issue's UUID (and prompts once, interactively, for a team UUID printed by its first probe). The probe is read-only: the mutations are checked by introspecting their input types, never by writing to your tracker.

Notes

• Linear personal API keys are sent as Authorization: <key> with no Bearer prefix.
• Linear reports most failures as HTTP 200 with a top-level errors array, so the client checks the response body rather than the status code.
• Team, state, label, and user metadata is cached for the lifetime of the server process. Restart the server after changing a team's workflow states or labels.