mcp-linear
Provides tools for interacting with Linear's API, enabling AI agents to manage issues, comments, teams, workflow states, labels, and users programmatically through the Linear platform.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-linear Show me my open issues in the Engineering team"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Fetch an issue by identifier |
| Issues assigned to the API key's owner |
| Full-text search with team/state/assignee filters |
| Create an issue on a team |
| Update fields on an existing issue |
| Comments on an issue |
| Post a comment |
| Team keys and names |
| Workflow states for a team |
| Labels on a team plus workspace labels (team optional) |
| Active users |
Related MCP server: Linear MCP Server
Setup
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env
# Edit .env — set LINEAR_API_KEYGet 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/pytestAll 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 comparatorteam-scoped labels via
team { labels }the root
issueLabelsconnectionviewer.assignedIssues(orderBy: updatedAt)every field the three mutations send —
IssueCreateInput,IssueUpdateInputandCommentCreateInputall acceptteamId,title,description,stateId,assigneeId,priority,labelIds,issueIdandbodyas used
One divergence was found and fixed:
Full-text search.
issueSearchrejects itsqueryargument as deprecated. Search now usessearchIssues(term: ...), which returnsIssueSearchPayloadwhose nodes areIssueSearchResult, notIssue— so it cannot spread theIssueFieldsfragment.queries.pydeclares a second fragment,SearchFields, with the identical selection on that type. Introspection confirmedIssueSearchResultcarries every fieldIssueFieldsselects. If you change one fragment, change the other.
One thing remains unconfirmed:
Workspace labels. The root
issueLabelsconnection 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 noBearerprefix.Linear reports most failures as HTTP 200 with a top-level
errorsarray, 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.
Available Tools
11 toolsadd_commentA
Post a comment on a Linear issue. Markdown is supported. identifier: human issue identifier, e.g. "GOV-123".
Inputs: body (required), identifier (required).
create_issueA
Create a Linear issue. Returns the created issue including its new identifier. team: team key or name, e.g. "GOV". assignee: user display name or email. See list_users. state: workflow state name, e.g. "Backlog". See list_states. priority: 0 none, 1 urgent, 2 high, 3 medium, 4 low. labels: label names on that team. See list_labels.
Inputs: team (required), title (required), state, labels, +3 more.
get_commentsA
Fetch the comments on a Linear issue, oldest first. identifier: human issue identifier, e.g. "GOV-123".
Inputs: identifier (required). Returns: result
get_issueA
Fetch a Linear issue by its human identifier, e.g. "GOV-123". Returns title, description, state, assignee, team, priority, labels, URL, and the git branch name Linear suggests for the issue.
Inputs: identifier (required).
list_labelsA
List the issue labels that can be applied to an issue, as {name}.
team: optional team key or full team name. With a team, returns that team's
own labels followed by the workspace-wide labels; without one, the
workspace-wide labels only. Names are what create_issue and update_issue
accept for labels.
Inputs: team. Returns: result
list_my_issuesA
List issues assigned to the owner of the configured API key, most recently
updated first.
state: optional state-name filter, e.g. "In Progress". Case-insensitive.
The filter is applied after the fetch, so passing one makes the server
over-fetch (four times limit, at least 50 issues) and then cut the
result back to limit. It is therefore best-effort within that window:
a matching issue further down the list than the window reaches is not
returned. Raise limit if you suspect one is missing.
limit: maximum number of issues returned.
Inputs: limit, state. Returns: result
list_statesA
List the workflow states for a team, in workflow order, as {name, type}.
These names are what create_issue and update_issue accept for state.
team: team key or full team name.
Inputs: team (required). Returns: result
list_teamsA
List Linear teams as {key, name}. Team keys are the prefix of issue identifiers, e.g. the GOV in GOV-123.
Inputs: no named parameters. Returns: result
list_usersA
List active Linear users as {name, email}. name is the display name that
create_issue and update_issue accept for assignee.
query: optional case-insensitive substring filter over name and email.
Inputs: query. Returns: result
search_issuesA
Full-text search over Linear issues, with optional filters.
team: team key or full team name, e.g. "GOV" or "Governance".
state: workflow state name, e.g. "In Progress". Resolved against the team's
workflow when team is given; without a team there is no workflow to
resolve against, so the value is sent as written and must match the state
name Linear stores.
assignee: user display name, full name, or email. See list_users.
Names are resolved the same way create_issue resolves them: a name that does
not match returns an error listing the valid options, not an empty result.
Inputs: query (required), team, limit, state, +1 more. Returns: result
update_issueA
Update fields on an existing Linear issue. Only the fields you pass are changed. identifier: human issue identifier, e.g. "GOV-123". state, assignee, labels: names, resolved against the issue's own team. priority: 0 none, 1 urgent, 2 high, 3 medium, 4 low. Passing labels replaces the issue's labels entirely.
Inputs: identifier (required), state, title, labels, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool targets a distinct resource or action: list_* clearly separates teams, states, labels, users, and my issues, while get_issue, search_issues, and list_my_issues offer different retrieval modes. Comments, creation, and updates are also cleanly separated with no overlapping responsibilities.
The tools consistently follow a verb_noun snake_case pattern: list_teams, list_states, get_issue, create_issue, update_issue, add_comment, and so on. list_my_issues is a minor variation but still predictable and fits the overall naming logic.
With 11 tools, the server is well-scoped for a Linear issue-management integration. It provides reference lookups, issue operations, and comments without redundant or unnecessary tools.
The core issue lifecycle is covered: create, get, update, search, list-my-issues, and comments, plus supporting lookups for teams, states, labels, and users. Obvious gaps like deleting/archiving issues or listing all issues in a team are minor and can often be worked around with search_issues.
Maintenance
Related MCP Connectors
Search, read and create Linear issues, projects, teams and cycles.
Issues, projects, cycles, and roadmaps via the official Linear hosted MCP server.
Find and manage issues, projects, and documents in your Linear workspace.
Unofficial Linear MCP — wraps the Linear GraphQL API (OAuth)
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAllows LLMs to integrate with Linear's issue tracking system, enabling them to create, update, search, and comment on issues through the Linear API.-
- AlicenseBqualityDmaintenanceEnables interaction with Linear's API to manage issues, projects, and teams. Supports creating, updating, searching, and deleting issues, along with project management and team operations through API key authentication.13578 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to interact with Linear's issue tracking system, including creating, updating, searching issues, adding comments, and accessing resources via the Linear API.MIT
- AlicenseAqualityDmaintenanceEnables AI agents to search, create, update, and manage Linear issues through natural language, with support for teams, workflows, and comments.9418 npm1MIT