Provides read-only tools for interacting with Linear, including listing teams, cycles, issues in a cycle, getting issue details, and searching issues.
Click on "Install 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., "@linear-mcp list issues in the current cycle"
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.
A small, read-only Model Context Protocol server for Linear. Bring your own Linear API key.
Written because none of the existing community Linear MCP servers were maintainers I wanted to trust with a personal API key, and because the surface I actually needed (list issues in a cycle, get an issue, search) is small enough to own outright.
Five read-only tools:
Tool | Purpose |
| Enumerate teams in the workspace (key, name, UUID). |
| List cycles for a team, filterable by past / current / future. |
| Issues in a specific cycle. Accepts |
| Full details for one issue, including description, labels, and recent comments. |
| Text search across the workspace's issues, optionally scoped to a team. |
No mutation tools — this server can't create, edit, or delete anything in Linear. That's a deliberate choice; adding write tools is a separate PR.
Related MCP server: Linear Cache MCP
Requires Node 20 or later.
git clone https://github.com/puneetsharma2791/linear-mcp.git
cd linear-mcp
npm install
npm run buildThat produces dist/index.js, which is the executable the MCP host will run.
Click Create key, name it something like "MCP - laptop".
Copy the key — it starts with lin_api_. You won't see it again.
The key inherits your Linear permissions, so this server will see whatever you can see in the Linear app.
Edit your MCP client config (for Claude Code, typically
~/.config/claude/claude_desktop_config.json or the equivalent per OS; for
Claude Code CLI check claude --help):
{
"mcpServers": {
"linear": {
"command": "node",
"args": ["/absolute/path/to/linear-mcp/dist/index.js"],
"env": {
"LINEAR_API_KEY": "lin_api_..."
}
}
}
}Restart the client. Tools will appear as linear__list_teams,
linear__get_issue, etc.
Any MCP client that speaks stdio works. Point its "server command" at
node /absolute/path/to/linear-mcp/dist/index.js and pass LINEAR_API_KEY
in the environment.
cp .env.example .env # then paste your API key
npm install
npm run dev # tsc --watch — rebuilds on editSmoke-test the built server by piping an MCP handshake in on stdin:
LINEAR_API_KEY=lin_api_... node dist/index.js < /dev/null &
# The server will exit cleanly on stdin close. To exercise a tool call,
# see the MCP inspector: https://github.com/modelcontextprotocol/inspectorEach tool is one file under src/tools/ with three exports:
a schema ({name, description, inputSchema}) — declared to the MCP client
a zod parser — validates arguments at call time
an async handler — runs the query and returns a plain object
Then add one entry each to ListToolsRequestSchema and the dispatch
switch in src/index.ts. That's the whole flow.
MIT. See LICENSE.
Fetch full details for one Linear issue. Accepts either the human identifier (e.g. 'HYD-123') or the internal UUID. Returns description, state, assignee, cycle, labels, and the most recent comments.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Issue identifier ('HYD-123') or UUID. | |
| include_comments | No | When true (default), include the last 20 comments. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description transparently lists returned fields and mentions the include_comments parameter. It lacks details on idempotency or error scenarios, but is sufficient for a read-only fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences: first states purpose, second lists return fields. No unnecessary words, and the critical information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-issue fetch with 2 parameters and no output schema, the description covers all relevant details: what is returned and how to identify the issue.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers 100% of parameters; description adds an example (HYD-123) and reinforces the dual form of the id, providing marginal extra value over the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches full details for one Linear issue, distinguishing it from sibling tools like search_issues by specifying it requires an identifier.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you have an issue identifier, but does not explicitly contrast with alternatives like search_issues for unfiltered queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cycles (sprints) for a team. Cycles have per-team monotonic numbers (HYD-cycle-2 is different from another-team-cycle-2). Filter by scope to narrow to only past, current, or future cycles.
| Name | Required | Description | Default |
|---|---|---|---|
| team | Yes | Team key (e.g. 'HYD') OR the team's UUID. Team keys are matched case-insensitively. | |
| limit | No | Max cycles to return. Default 20. | |
| scope | No | Which cycles to return. Default 'all'. 'current' is the one active at the request time; 'past' and 'future' are relative to now. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that cycles have per-team monotonic numbers, adding useful context. However, it does not mention any behavioral traits like idempotency, safety, or rate limits, which would be helpful for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and every word adds value. No unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and full schema coverage, the description is largely complete. It could optionally mention the return structure, but with no output schema, it does not need to describe it. The description covers input and key behavior adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds value by explaining the per-team monotonic numbering and clarifying that scope filtering is relative to now. This goes beyond the schema but does not deeply elaborate on each parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'cycles (sprints) for a team'. It distinguishes from siblings like list_issues_in_cycle by specifying that it returns cycles themselves, not issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implicitly indicates when to use (to get cycles for a team) and mentions filtering by scope. However, it lacks explicit when-not-to-use or alternatives among siblings, though context and sibling names provide some guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List issues in a Linear cycle. Provide EITHER cycle_id (from list_cycles) OR both team and cycle_number. Returns identifier, title, state, assignee, priority, estimate — enough to render a cycle overview.
| Name | Required | Description | Default |
|---|---|---|---|
| team | No | Team key (e.g. 'HYD') or UUID. Required if cycle_id is not given. | |
| limit | No | Max issues to return. Default 50. | |
| state | No | Filter by rough state category. Default 'all'. 'open' excludes issues in a completed or canceled state. | |
| cycle_id | No | Cycle UUID (from list_cycles). | |
| cycle_number | No | Per-team cycle number. Required if cycle_id is not given. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavioral traits. It states the return data and implies a read-only operation, but does not mention pagination behavior, rate limits, or authentication requirements. It is adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no wasted words. The description is front-loaded with the primary action and immediately provides usage instructions and return value summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has 5 parameters with no output schema. The description explains how to use the parameters together and lists return fields. It does not explain the limit parameter's pagination behavior or sorting, but overall it is fairly complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying the mutual dependency between cycle_id or (team + cycle_number) and noting that cycle_id comes from list_cycles. This helps beyond the schema's standalone descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the action 'List issues in a Linear cycle' and specifies two ways to identify the cycle. It lists the return fields, distinguishing it from siblings like list_cycles (which lists cycles) and search_issues (which is broader).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says to provide either cycle_id or both team and cycle_number, and references list_cycles as a source for cycle_id. It does not give explicit negative guidance or compare to search_issues, but the instruction is clear for when to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List every team in the Linear workspace. Returns each team's identifier (key), human-readable name, and UUID. Use this first when you don't know a team's key.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description adequately discloses it returns specific fields (key, name, UUID) for all teams. Does not mention pagination or rate limits, but acceptable for a simple list.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no unnecessary words, front-loaded with action verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a parameterless list tool without output schema. Describes purpose and return fields.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100%. Description adds no param info but none is needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it lists every team, returns key, name, UUID. Distinct from sibling tools like get_issue and list_cycles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit recommendation: 'Use this first when you don't know a team's key.' Lacks explicit when-not-to-use but gives clear context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the workspace's issues by text. Matches title, description, and comments. Returns identifier, title, state, URL — shape aligned with list_issues_in_cycle so results can be treated the same way.
| Name | Required | Description | Default |
|---|---|---|---|
| team | No | Optional. Restrict to a single team by key ('HYD') or UUID. | |
| limit | No | Max results. Default 20. | |
| query | Yes | Text to search for (matches title, description, comments). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully discloses the search behavior (matches title, description, comments) and output fields. It implicitly indicates a read-only operation, though it does not explicitly state it is not destructive. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and contains no extraneous information. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the tool's purpose, search scope, and output alignment with a sibling tool. It lacks details on pagination, ordering, or error handling, but given the simple parameter set and no output schema, it provides sufficient context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by clarifying that the query parameter matches title, description, and comments, and by listing the return fields not specified in the schema. This goes beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('search') and resource ('issues'), and explicitly states what fields are matched (title, description, comments) and what is returned (identifier, title, state, URL). It also distinguishes from sibling tools like get_issue and list_issues_in_cycle by specifying search behavior and output alignment.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states when to use the tool (to search issues by text) and provides context about result shape alignment with list_issues_in_cycle, enabling interchangeable use. However, it does not explicitly mention when not to use it or provide alternatives for non-search tasks.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_issuelist_cycleslist_issues_in_cyclelist_teamssearch_issuesEach tool has a clearly distinct purpose: fetching a single issue, listing cycles, listing issues in a cycle, listing teams, and searching issues. No overlap in functionality.
All tool names follow a consistent verb_noun pattern (get_issue, list_cycles, list_issues_in_cycle, list_teams, search_issues), making it predictable.
5 tools is well-scoped for a Linear workspace, covering the core entities (teams, cycles, issues) without unnecessary tools.
The set covers read operations comprehensively but lacks any create/update/delete tools for issues or other entities, which is a notable gap for a project management server.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
MCP server for Linear project management and issue tracking
Linear MCP — wraps the Linear GraphQL API (OAuth)
Search, read and create Linear issues, projects, teams and cycles.
An MCP server that provides access to Testiny projects, test cases and test runs
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/puneetsharma2791/linear-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
