Linear MCP: The Developer's Guide to Linear's Model Context Protocol Server

Linear MCP is Linear's official Model Context Protocol server. It's a remote, authenticated server hosted by Linear that lets any MCP-compatible AI model or agent read and act on your Linear data: finding, creating, and updating issues, projects, and comments through a single endpoint at https://mcp.linear.app/mcp. No more copy-pasting ticket details into a chat window. You connect a client like Claude, Cursor, or VS Code once, and the model queries and edits your tracker directly. This guide covers what the server does, how it differs from community projects, how to set it up, what it can do, and how to keep it secure.

What the Linear MCP server is

Linear, the issue-tracking and project-management product, announced its official MCP server on May 1, 2025. The changelog describes it as a way for "your AI models and agents [to] use our official MCP server to access your Linear data in a simple and secure way." Linear hosts and manages it centrally. It follows the authenticated remote MCP spec, and per the changelog, was built with help from Linear's "partners at Cloudflare and Anthropic."

The whole point of MCP is giving AI tools a uniform way to reach external systems. The Model Context Protocol is an open standard, and Linear ships a server for it so agents can act inside Linear without anyone writing a bespoke integration. The official scope, per Linear's docs, is "tools available for finding, creating, and updating objects in Linear like issues, projects, and comments — with more functionality on the way."

It's a hosted remote server, so there's nothing to install for the default path and no API keys to juggle. Authentication happens in your browser the first time you connect.

Official vs. community servers (be careful here)

Search GitHub for "linear mcp" and you'll find several similarly named projects: jerhadf/linear-mcp-server, tacticlaunch/mcp-linear, magarcia/mcp-server-linearapp, dvcrn/mcp-server-linear, and more. These are community projects that typically wrap Linear's public API. They are not Linear's hosted server. Some add features the official server lacks. Multi-workspace support is the most common reason teams reach for a community option, since you self-host them with a personal API key.

For most people, the official server at mcp.linear.app is the right default: OAuth-based, hosted, easiest to connect. Reach for a community server when you specifically need multi-workspace support, fuller GraphQL coverage, or to run everything on your own infrastructure.

What the Linear MCP server can do

Linear's own docs frame the capability as finding, creating, and updating issues, projects, and comments. Third-party toolkits and analyses (Composio, Fiberplane) report roughly two to three dozen tools, which covers a lot more than basic issue CRUD:

• Query and read issues, projects, teams, users, documents, cycles, and comments.
• Create and update issues, projects, comments, and labels.
• Manage milestones on projects.
• Attachments and images. Create attachments via upload, and extract images from markdown (screenshots in an issue description, for example).

The exact tool count comes from third parties and varies by toolkit. Linear doesn't state it verbatim, so treat specific numbers as approximate. Here's the practical takeaway. The server is an abstraction layer over Linear's GraphQL API with task-oriented tools, not a thin pass-through.

Prompts that work in practice:

• "Create a Linear ticket for the authentication work we just discussed and assign it to Sarah."
• "What are the lowest-effort open issues assigned to me?" (querying by assignee and a label like "low hanging fruit").
• "Summarize this long discussion thread and turn the decisions into tickets."

How to set up the Linear MCP server

Setup differs slightly per client, but they all point at the same URL: https://mcp.linear.app/mcp.

Authentication: OAuth 2.1 or a Bearer token

The primary auth method is an interactive OAuth 2.1 flow with dynamic client registration. It's browser-based, with no key management. You can also pass an OAuth token or API key directly in an Authorization: Bearer <yourtoken> header. The header approach is handy when you're acting as an app user, granting read-only access through a restricted API key, or reusing an existing Linear OAuth application.

A quick note on transport. The May 2025 launch originally used an SSE endpoint at https://mcp.linear.app/sse. That endpoint is being deprecated in favor of the Streamable HTTP endpoint at https://mcp.linear.app/mcp. If a third-party guide tells you to use --transport sse and the /sse URL, it's probably outdated. Use /mcp unless you specifically need the SSE fallback (see WSL below).

Claude Code

Add the server with one command, then authenticate inside a session:

claude mcp add --transport http linear-server https://mcp.linear.app/mcp

Then open a Claude Code session and run:

/mcp

This launches the OAuth browser flow to complete the connection.

Claude Desktop and Claude Team/Enterprise

No config file to edit. In Claude Desktop, go to Settings > Connectors and add the Linear connector. On Claude Team/Enterprise, use the connectors page and connect Linear directly.

Cursor

Install via Cursor's MCP tools directory (search "Linear") or the install deeplink. Prefer a manual config? Add it through the mcp-remote bridge described below.

Codex

Codex connects to the remote URL via its CLI:

codex mcp add linear --url https://mcp.linear.app/mcp

This requires experimental_use_rmcp_client = true in the [features] section of ~/.codex/config.toml, after which you authenticate with:

codex mcp login linear

VS Code, Windsurf, and Zed (the mcp-remote bridge)

Clients that only speak stdio bridge to the remote server using the mcp-remote adapter, run through npx. For VS Code and Windsurf, use this JSON config:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"]
    }
  }
}

Zed wants a slightly different shape:

{
  "context_servers": {
    "linear": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"],
      "env": {}
    }
  }
}

For any other MCP-compatible tool without native remote support, the pattern's the same: command npx, args -y mcp-remote https://mcp.linear.app/mcp. Make sure you're on a current Node.js version, since the bridge runs through npx.

Verify the connection

Once connected, ask the model something read-only first. Try "List my open Linear issues" to confirm the tools are wired up before you let it create or change anything.

From assistants to autonomous agents

Everything above describes a human in an AI client typing prompts that call Linear tools. There's a second mode. Autonomous agents use the Linear MCP server as a tool and act on Linear without a person prompting each step, triggered by events like a pull request merging, an alert firing, or a support ticket landing.

Teams are already running this. The Pragmatic Engineer's MCP deep dive describes Gradient Labs using Claude Code plus the Linear MCP to aggregate crowdsourced test results from a Notion database, then create a new Linear project populated with tickets. The Cyrus integration reports closing 38 issues in three weeks (versus a usual 15–20) using Linear labels as triggers ("bug" routes to a debugger mode, "feature" to a builder mode). Those are self-reported vendor metrics, though, and around 13% of issues still needed human intervention before merge.

This is exactly the layer gamut.so (the AI agent knowledge-workforce product from Datawizz) operates in. Agents pick up an external event, use MCP servers like Linear's as tools to query, create, or update issues, and keep the system of record current, without a human in the loop for every step. The Linear MCP server is the same building block whether a developer drives it from Cursor or an autonomous agent calls it on a trigger.

Security and governance

The Linear MCP server respects the permissions of the authenticating Linear account. That's also the risk. It returns everything that user can see, which in an enterprise can include PII, source code, and other regulated content (Strac, MintMCP). For regulated data, add a DLP/redaction layer at the MCP boundary that inspects tool responses before they reach the model.

There's also a structural risk baked into MCP itself, not specific to Linear: prompt injection. An agent that reads external content (an issue description or comment) and then acts on it can be manipulated by instructions hidden in that text. Issue and comment fields are attacker-controllable surfaces, so this matters. Recommended mitigations are layered rather than single-point (Obot, Glama): scope agent tools tightly, log activity, and require human confirmation for high-risk actions. Client-side protections vary, so don't lean on any single client's guardrails. Keep the controls above at the boundary you own.

One more piece of least-privilege advice. When you only need read access, pass a restricted, read-only API key via the Bearer header instead of granting full OAuth scope.

Troubleshooting common errors

OAuth failures are the most common real-world problem, and they're well documented:

• Invalid client / Invalid redirect URI / re-auth every session. The widely reported fixes: clear the auth cache, remove and re-add the server, or revoke and reauthorize the app in Linear. See the Cursor forum thread and this Claude Code issue.
• Clear a broken OAuth cache:

rm -rf ~/.mcp-auth

• WSL/Windows. Linear's docs note WSL compatibility issues. Falling back to the SSE transport (the /sse endpoint) is the documented workaround there.
• Node version. The mcp-remote bridge runs through npx, so an outdated Node.js install can cause connection failures. Update Node and retry.
• Bearer fallback. If OAuth keeps failing, switching to direct API-key auth via the Authorization: Bearer header sidesteps the OAuth flow entirely.

FAQ

What is the Linear MCP server? Linear's official Model Context Protocol server. It's a hosted, secure interface that lets any compatible AI client find, create, and update Linear issues, projects, and comments.

What is the Linear MCP server URL? https://mcp.linear.app/mcp (Streamable HTTP). The older https://mcp.linear.app/sse endpoint is being deprecated.

Is the Linear MCP server free? Connecting to and using the official server is free and works on all Linear plans, including the free tier. You pay only for the LLM tokens your AI client consumes.

Do I need an API key? No. The default flow uses browser-based OAuth 2.1. An API key passed via a Bearer header is an optional alternative, useful for read-only or restricted access.

Is the Linear MCP server secure? It uses OAuth and respects your Linear permissions, but it returns everything your account can see. Enterprises handling regulated data should add DLP/redaction at the MCP layer and require confirmation for high-risk actions.

Official vs. community Linear MCP, which should I use? Use the official hosted server for the easiest, OAuth-based single-workspace setup. Reach for a community server when you need multi-workspace support, fuller GraphQL coverage, or full self-hosted control.

Why is my Linear MCP authentication failing? Common OAuth errors include "Invalid client" and "Invalid redirect URI." Clear ~/.mcp-auth, re-add the server, reauthorize in Linear, update Node, try the SSE transport on WSL, or fall back to Bearer-token auth.

Next steps

The Linear MCP server is a small, free thing to add and a big change in how an AI tool relates to your tracker. It goes from chat partner to operator that reads and acts on your work. Connect it to whichever client you already use, start with read-only prompts, and tighten permissions before you let anything write. From there, the same server is what autonomous agents call when you're ready to move from assisting to automating.