Linear MCP server setup for Claude Code and Cursor

Quick answer: The Linear MCP server is a Node process that wraps the Linear GraphQL API as MCP tools. Install with one npx command, drop a personal API key into the env block, and Claude Code or Cursor can read, create, and update issues. Setup takes 5 minutes, tested on server version 0.2.4 on April 15, 2026.

The Linear MCP server connects your coding agent to your issue tracker. Instead of asking Claude to guess which bugs are open, it reads them. Instead of dictating new issues through chat, the agent creates them in one tool call with the right team, priority, and assignee.

This guide covers installation, config for both editors, the prompt patterns that work, and the rough edges you will find after a week.

What this server does

The server exposes about 18 Linear tools backed by the official Linear GraphQL API. When Claude wants to create an issue, it calls create_issue with a team ID, title, and description. When it wants to find open bugs, it calls search_issues with a filter object.

Main tool groups:

• Issues: create_issue, get_issue, update_issue, delete_issue, search_issues
• Comments: create_comment, list_comments
• Projects: list_projects, get_project
• Teams: list_teams, get_team
• Users: list_users, get_user
• Cycles: list_cycles, get_current_cycle
• Labels: list_labels, add_label_to_issue

Because the server runs locally, your API key stays on your machine. The server holds it in memory and sends it as a bearer token on every GraphQL request.

Installing Linear MCP

The package is published on npm as linear-mcp-server. You do not need a global install - the npx -y prefix fetches on first launch and caches. Cold start is about 2 seconds and pulls around 3 MB.

Before you touch any config, create a Linear API key:

1. Open Linear and navigate to Settings > API.
2. Click "Create key" and name it something identifiable like "Claude Code MCP."
3. Copy the key. It starts with lin_api_.
4. The key inherits your user permissions - it can see every team and project you can see. Linear does not offer per-team API keys at this tier.

If you want a narrower scope, create a service user, add it only to the teams the agent should touch, and mint the key under that account.

Configuring for Claude Code

Claude Code reads MCP servers from ~/.claude/mcp.json globally or .mcp.json per project. Add a linear entry with the API key in env:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

Restart Claude Code. Run /mcp and you should see the server listed with around 18 tools. Call list_teams as a smoke test - if it returns your team slugs, the wiring is correct.

For team projects, commit a .mcp.json with a placeholder and store the real key in a shell env var. Claude Code expands env references at spawn time, so "LINEAR_API_KEY": "$LINEAR_API_KEY" works.

Configuring for Cursor

Cursor uses the same spec, reading from ~/.cursor/mcp.json. The JSON is identical:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

Open Cursor settings > MCP and toggle the server on. Cursor spawns the process on the first tool call. Latency runs 200 to 400 ms per GraphQL call on a fast connection.

Example prompts and workflows

Once the server is attached, Linear acts like an API the agent can reach. A few prompts:

• "Create a bug in the Frontend team titled Header overlaps hero on mobile with priority 2 and assign it to me."
• "List every open issue in the current cycle for the Backend team and group by assignee."
• "Find issues with the needs-design label and add a comment asking for an update."
• "Move every issue in the Sprint 42 milestone that is still open to Sprint 43."
• "Search issues modified in the last 7 days where the title contains auth and show the state and owner."

The model chains calls automatically. Creating an issue typically runs list_teams to resolve the team slug, then create_issue with the resolved ID. Two calls per issue.

One pattern that saves time: pass Linear IDs directly when you have them. If you say "update issue ENG-142," the agent skips the search step and hits update_issue immediately.

Troubleshooting

Tool call returns 401 Unauthorized. The API key is wrong, revoked, or expired. Regenerate under Settings > API and restart the MCP server.

Tool call returns 403 Forbidden. The key is valid but your user account does not have access to that team or project. Grant access in Linear or rotate the key to a user with broader permissions.

GraphQL errors reference unknown field. The server version is older than your Linear workspace schema. Upgrade with npm install -g linear-mcp-server@latest and clear the npx cache.

Issue creation fails with missing required field. Linear requires a team ID on every issue. If the agent omits it, tell it the team slug or ID explicitly. The server does not guess a default team.

Server fails with ENOENT. npx is not on PATH in the env the editor inherits. Launch from a terminal or set the absolute path to npx in the config.

Alternatives

If the Linear server does not fit, a few options cover the same ground:

• jira-mcp is the Atlassian equivalent for teams on Jira Cloud or Server.
• github-mcp works well if your issues live on GitHub Issues rather than Linear.
• shortcut-mcp is the equivalent for teams on Shortcut.

For read-only reporting, a Linear webhook piped into a local SQLite file is faster than querying the API every prompt. You lose live data but gain zero rate limits.

The Linear MCP server is the right default for any team that already runs on Linear. Five minutes of setup replaces a lot of tab-switching during the week. Keep the key scoped to a service user if you want the blast radius to stay small.