Problem: Switching to Linear's UI Breaks Your Flow

MCP Linear server lets you create, search, and update Linear issues directly from Claude Desktop — no tab switching, no dashboard clicking, no context loss.

If you're mid-session debugging a bug and need to file a ticket, opening Linear breaks your momentum. With the Linear MCP server connected to Claude Desktop, you prompt Claude like a teammate: "Create a high-priority bug in the Backend team titled 'Auth token expiry not handled on mobile'." Done. Back to coding.

You'll learn:

How to generate a Linear API key and configure the MCP server
How to wire the server into Claude Desktop's claude_desktop_config.json
How to create, search, and update issues from Claude's chat interface

Time: 15 min | Difficulty: Intermediate

Why This Works

Linear exposes a GraphQL API. The MCP server wraps it as a set of tools Claude can call — create_issue, search_issues, update_issue, list_teams, and more. Claude Desktop reads your MCP config on startup and registers those tools. From that point on, any prompt that references Linear issues routes through the server without you touching the Linear UI.

What you need:

Claude Desktop installed (macOS or Windows)
Node.js 18+ (Node 22 recommended)
A Linear workspace with admin or member access

Solution

Step 1: Generate a Linear API Key

Open Linear → your workspace → Settings → API
Under Personal API keys, click Create key
Name it claude-mcp and copy the value — it starts with lin_api_

You won't see this key again. Paste it somewhere safe before closing.

Step 2: Install the Linear MCP Server

The simplest path is npx — no global install needed:

# Test the server runs before wiring it into Claude
LINEAR_API_KEY=lin_api_yourkey npx -y linear-mcp-server

Expected output:

Linear MCP Server running on stdio

Press Ctrl+C to stop. If you see Missing LINEAR_API_KEY, the env var didn't export — prefix it on the same line as shown above.

Alternative: Smithery auto-install

# Installs and configures Claude Desktop automatically
npx @smithery/cli install linear-mcp-server --client claude

Smithery edits claude_desktop_config.json for you. Skip Step 3 if you use this path.

Step 3: Add the Server to Claude Desktop Config

Open the Claude Desktop config file:

# macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows
notepad %APPDATA%\Claude\claude_desktop_config.json

Add the linear block inside mcpServers:

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

If mcpServers doesn't exist yet, create the full structure above. If you already have other servers (e.g. GitHub, Supabase), add linear as a sibling key inside mcpServers.

If you get a JSON syntax error after editing, run the repair script:

npx linear-mcp-server repair:claude

Step 4: Restart Claude Desktop

Fully quit Claude Desktop (don't just close the window — use Quit from the menu or taskbar). Reopen it.

To confirm the server loaded, look for the tools icon (🔧) in the chat composer. Clicking it should list Linear tools including search_issues and create_issue.

Verification

Try this prompt in Claude Desktop:

List my assigned Linear issues with high or urgent priority

You should see: Claude call get_my_issues or search_issues and return a formatted list of your Linear issues with title, status, and priority.

Test issue creation:

Create a bug in the Engineering team titled "Login redirect broken on Safari 17" with high priority

You should see: Claude return a confirmation with the new issue ID (e.g. ENG-204) and a link to the issue in Linear.

Verify it appeared in Linear by checking your team's backlog.

Available Tools Reference

Once connected, Claude can use these tools:

Tool	What it does
`create_issue`	New issue with title, description, priority, assignee, labels
`update_issue`	Modify any field on an existing issue by ID
`search_issues`	Filter by team, status, assignee, priority, text query
`get_my_issues`	Issues assigned to the authenticated user
`list_teams`	All teams in the workspace
`create_comment`	Add a markdown comment to an issue

Priority values: 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low.

What You Learned

The Linear MCP server bridges Claude Desktop and Linear's GraphQL API over stdio — no OAuth flow, just an API key
Claude Desktop loads MCP servers at startup from claude_desktop_config.json — a full restart is required after config changes
npx -y linear-mcp-server always pulls the latest version; pin a version with linear-mcp-server@x.x.x in args if you need stability

Limitation: The server authenticates with a personal API key, not an OAuth token — issues you create will show your name as author. For a bot identity, create a dedicated Linear service account and generate the key from there.

Tested on linear-mcp-server 1.x, Node 22, Claude Desktop 0.9, macOS Sequoia and Windows 11

FAQ

Q: How do I assign an issue to someone else, not myself? A: Ask Claude to include the assignee by name: "Create a bug assigned to @sarah." The server resolves names to Linear user IDs automatically.

Q: What is the difference between linear-mcp-server and the Composio Linear MCP? A: linear-mcp-server talks directly to Linear's API using your personal key — no third-party platform in the middle. Composio's version adds OAuth and session management, which matters for multi-user apps but adds latency for personal use.

Q: Does this work on Windows without WSL? A: Yes. Use the same npx command in the config. Make sure Node 18+ is on your Windows PATH — the LINEAR_API_KEY env var is passed directly by Claude Desktop, no shell profile needed.

Q: Can I use this MCP server in Cursor or Claude Code at the same time? A: Yes. Each client has its own MCP config file. Add the same linear block to Cursor's settings and it runs as a separate process — the API key works across all clients simultaneously.