The Linear MCP Server enables programmatic interaction with Linear's API to manage issues, teams, and projects, facilitating integration with AI agents via the Model Context Protocol.
Issue Management: Create new issues with customizable properties (title, description, team, assignee, priority, labels), list issues with flexible filtering, update existing issues, retrieve specific issue details, and search issues with text queries.
Team Management: List all teams in the workspace with their IDs, names, keys, and descriptions.
Project Management: List all projects with optional team filtering, viewing details like name, description, and state.
Allows AI agents to manage issues, projects, and teams in Linear. Provides tools for creating, listing, and updating issues, as well as listing teams and projects through the Linear API.
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., "@Linear MCP Server create a new bug report for the mobile app 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.
Note: This is a custom implementation. For the official Cline Linear MCP server, see cline/linear-mcp.
A Model Context Protocol (MCP) server that provides tools for interacting with Linear's API, enabling AI agents to manage issues, projects, and teams programmatically through the Linear platform.
Issue Management
Create new issues with customizable properties (title, description, team, assignee, priority, labels)
List issues with flexible filtering options (team, assignee, status)
Update existing issues (title, description, status, assignee, priority)
Team Management
List all teams in the workspace
Access team details including ID, name, key, and description
Project Management
List all projects with optional team filtering
View project details including name, description, state, and associated teams
Related MCP server: Linear MCP Server
Node.js (v16 or higher)
A Linear account with API access
Linear API key with appropriate permissions
Get your Linear API key from Linear's Developer Settings
Run with your API key:
LINEAR_API_KEY=your-api-key npx @ibraheem4/linear-mcpOr set it in your environment:
export LINEAR_API_KEY=your-api-key
npx @ibraheem4/linear-mcpClone the repository:
git clone [repository-url]
cd linear-mcpInstall dependencies:
npm installBuild the project:
npm run buildFor local development and debugging, you can use the MCP Inspector:
Install supergateway:
npm install -g supergatewayUse the included run.sh script:
chmod +x run.sh
LINEAR_API_KEY=your-api-key ./run.shAccess the Inspector:
Open localhost:1337 in your browser
The Inspector connects via Server-Sent Events (SSE)
Test and debug tool calls through the Inspector interface
Configure the MCP server in your settings file based on your client:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"linear-mcp": {
"command": "node",
"args": ["/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "your-api-key-here"
},
"disabled": false,
"alwaysAllow": []
}
}
}Location: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json
{
"mcpServers": {
"linear-mcp": {
"command": "node",
"args": ["/path/to/linear-mcp/build/index.js"],
"env": {
"LINEAR_API_KEY": "your-api-key-here"
},
"disabled": false,
"alwaysAllow": []
}
}
}For Cursor, the server must be run with the full path:
node /Users/ibraheem/Projects/linear-mcp/build/index.jsCreates a new issue in Linear.
{
title: string; // Required: Issue title
description?: string; // Optional: Issue description (markdown supported)
teamId: string; // Required: Team ID
assigneeId?: string; // Optional: Assignee user ID
priority?: number; // Optional: Priority (0-4)
labels?: string[]; // Optional: Label IDs to apply
}Lists issues with optional filters.
{
teamId?: string; // Optional: Filter by team ID
assigneeId?: string; // Optional: Filter by assignee ID
status?: string; // Optional: Filter by status
first?: number; // Optional: Number of issues to return (default: 50)
}Updates an existing issue.
{
issueId: string; // Required: Issue ID
title?: string; // Optional: New title
description?: string; // Optional: New description
status?: string; // Optional: New status
assigneeId?: string; // Optional: New assignee ID
priority?: number; // Optional: New priority (0-4)
}Lists all teams in the workspace. No parameters required.
Lists all projects with optional filtering.
{
teamId?: string; // Optional: Filter by team ID
first?: number; // Optional: Number of projects to return (default: 50)
}Gets detailed information about a specific issue.
{
issueId: string; // Required: Issue ID
}For development with auto-rebuild:
npm run watchThe server includes comprehensive error handling for:
Invalid API keys
Missing required parameters
Linear API errors
Invalid tool requests
All errors are properly formatted and returned with descriptive messages.
Built with:
TypeScript
Linear SDK (@linear/sdk v37.0.0)
MCP SDK (@modelcontextprotocol/sdk v0.6.0)
The server uses stdio for communication and implements the Model Context Protocol for seamless integration with AI agents.
MIT
Create a new issue in Linear
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | Issue title | |
| description | No | Issue description (markdown supported) | |
| teamId | Yes | Team ID | |
| assigneeId | No | Assignee user ID (optional) | |
| priority | No | Priority (0-4, optional) | |
| labels | No | Label IDs to apply (optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description provides no behavioral details beyond stating it creates an issue. No mention of return values, permissions, or side effects.
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?
Very concise (one sentence) but lacks informational content. It is not wasteful, but it is under-specified for a tool with six parameters.
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 complexity (6 params, no output schema, no annotations), the description provides insufficient context. It does not explain what the tool returns or how to obtain required IDs like teamId.
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 the schema already describes all parameters. The description adds no additional meaning beyond what's in the schema, meeting the baseline.
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 action (create) and resource (issue in Linear). It distinguishes from sibling tools like create_comment, create_cycle, etc. However, it lacks nuance about what an 'issue' entails.
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?
No guidance on when to use this tool versus alternatives (e.g., update_issue, search_issues). No context about prerequisites or typical workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific issue
| Name | Required | Description | Default |
|---|---|---|---|
| issueId | Yes | Issue ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description lacks behavioral details such as read-only nature, authentication requirements, or response characteristics, which is particularly problematic without an output schema.
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?
Single sentence, no fluff. Efficiently conveys the tool's purpose.
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 tool with one parameter, the description is minimally adequate but omits what 'detailed information' includes. Lacks output schema, so more detail would be helpful.
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 has 100% description coverage with 'Issue ID'. The description adds no additional meaning beyond what the schema already provides, meeting the baseline.
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 'Get detailed information about a specific issue' clearly states the action (get) and resource (issue), and distinguishes it from sibling tools that create, update, or delete 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?
No guidance on when to use this tool versus alternatives like search_issues or list_issues. No context about use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List issues with optional filters
| Name | Required | Description | Default |
|---|---|---|---|
| teamId | No | Filter by team ID (optional) | |
| assigneeId | No | Filter by assignee ID (optional) | |
| status | No | Filter by status (optional) | |
| first | No | Number of issues to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions 'optional filters', failing to describe key traits such as pagination behavior (implied by 'first' parameter), rate limits, authentication needs, or whether it's read-only. This is a significant gap for a tool with multiple parameters and no output schema.
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 a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, making it easy to parse quickly without unnecessary elaboration.
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 complexity (4 parameters, no annotations, no output schema, and multiple sibling tools), the description is incomplete. It lacks details on behavioral traits, usage differentiation, and output expectations, leaving the agent with insufficient context to use the tool effectively beyond basic parameter input.
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 description coverage is 100%, so the schema fully documents all four parameters. The description adds no meaning beyond the schema, merely restating that filters are optional without explaining parameter interactions or semantics. Baseline 3 is appropriate as the schema does the heavy lifting.
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 'List issues with optional filters' states the basic action (list) and resource (issues), but it's vague about scope and doesn't differentiate from sibling tools like 'search_issues' or 'get_issue'. It lacks specificity about what 'list' entails (e.g., all issues, paginated, sorted).
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?
No guidance is provided on when to use this tool versus alternatives like 'search_issues' or 'get_issue'. The description mentions 'optional filters' but doesn't specify contexts or exclusions, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects
| Name | Required | Description | Default |
|---|---|---|---|
| teamId | No | Filter by team ID (optional) | |
| first | No | Number of projects to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description only states a read operation but lacks details on optional filtering, pagination defaults, or potential performance implications.
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?
Extremely concise but sacrifices completeness; front-loading is fine but could include key details like optional filters.
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?
Simple tool with two optional params and no output schema, but description omits context like pagination limit (default 50) and how it differs from other list tools.
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 both parameters; description adds no extra meaning beyond the schema, meeting the baseline.
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 'List all projects' with a specific verb and resource, but it does not differentiate from sibling list_* tools or clarify that filtering is available.
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?
No guidance on when to use this tool vs alternatives like search_issues or list_teams, nor any context on filtering or pagination usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all teams in the workspace
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or pagination behavior. The tool is likely read-only, but this is not explicitly stated.
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?
Single sentence with no filler words. Information is front-loaded and every word serves a purpose.
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 simple listing tool with no parameters, but lacks details about the return value format or pagination. With no output schema, the description could mention what fields are returned.
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?
The tool has zero parameters and schema coverage is 100%. With no parameters to describe, the baseline is 4. The description adds no parameter semantics but is not required to.
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 'List all teams in the workspace' uses a specific verb ('list') and resource ('teams') with scope ('in the workspace'), clearly distinguishing it from sibling tools that create, update, or get individual teams.
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?
No guidance on when to use this tool versus alternatives like 'get_team' for a specific team. The description does not mention exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for issues using a text query
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query text | |
| first | No | Number of results to return (default: 50) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions searching with a text query but fails to describe critical traits like whether results are paginated, sorted, or filtered beyond the query, what permissions are required, or how the search operates (e.g., full-text, exact match). This leaves significant gaps for a search 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 a single, efficient sentence that directly states the tool's function without unnecessary words. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.
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 complexity of a search operation with no annotations and no output schema, the description is incomplete. It lacks details on behavioral aspects (e.g., search scope, result format) and doesn't compensate for the absence of structured fields, making it inadequate for effective tool selection and invocation.
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?
The input schema has 100% description coverage, documenting both parameters ('query' and 'first') adequately. The description adds no additional meaning beyond what the schema provides, such as query syntax or result formatting. With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
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 action ('search for issues') and resource ('issues'), making the purpose evident. However, it doesn't differentiate from sibling tools like 'list_issues' or 'get_issue', which might also retrieve issues but with different mechanisms or scopes.
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?
No guidance is provided on when to use this tool versus alternatives such as 'list_issues' or 'get_issue'. The description implies usage for text-based queries but lacks explicit context or exclusions, leaving the agent to infer based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing issue
| Name | Required | Description | Default |
|---|---|---|---|
| issueId | Yes | Issue ID | |
| title | No | New title (optional) | |
| description | No | New description (optional) | |
| status | No | New status (optional) | |
| assigneeId | No | New assignee ID (optional) | |
| priority | No | New priority (0-4, optional) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Update an existing issue,' implying a mutation operation, but doesn't specify permissions required, whether changes are reversible, rate limits, or error handling. This leaves significant gaps in understanding the tool's behavior and risks.
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 a single, direct sentence with zero wasted words: 'Update an existing issue.' It's front-loaded and efficiently conveys the core action without unnecessary elaboration, making it highly concise and well-structured.
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 complexity as a mutation tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits, error cases, or what the update returns, leaving the agent under-informed about how to handle this operation effectively.
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?
The input schema has 100% description coverage, detailing all 6 parameters (e.g., 'issueId' as required, 'title' as optional). The description adds no additional meaning beyond the schema, such as explaining parameter interactions or constraints. Baseline score of 3 is appropriate since the schema does the heavy lifting.
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 'Update an existing issue' clearly states the action (update) and resource (issue), but it's vague about what aspects can be updated and doesn't distinguish it from sibling tools like 'create_issue' or 'get_issue'. It provides a basic purpose but lacks specificity about the scope of updates.
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 offers no guidance on when to use this tool versus alternatives such as 'create_issue' for new issues or 'get_issue' for viewing. It doesn't mention prerequisites like needing an existing issue ID or context for when updates are appropriate, leaving the agent without usage direction.
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.
v1.0.0create_issueget_issuelist_issueslist_projectslist_teamssearch_issuesupdate_issueScored across 7 tools
Every tool has a clearly distinct purpose with no ambiguity. Each tool targets a specific resource (issue, project, team) and action (create, get, list, search, update), making it easy for an agent to select the correct one.
All tools follow a consistent verb_noun pattern (e.g., create_issue, list_issues, update_issue). The naming is uniform and predictable throughout the set, with no deviations in style or convention.
With 7 tools, the count is well-scoped and appropriate for a Linear issue management server. Each tool earns its place by covering essential operations without being overly sparse or bloated.
The tool set provides strong CRUD coverage for issues (create, get, list, search, update) and lists for projects and teams. A minor gap exists in missing delete operations for issues, projects, or teams, but agents can still handle core workflows effectively.
Search, read and create Linear issues, projects, teams and cycles.
Linear MCP — wraps the Linear GraphQL API (OAuth)
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
MCP server for Linear project management and issue tracking
