How to Add the Linear MCP Server to Claude Code

Published August 7, 2026 · by the AQ team

Adding Linear to Claude Code takes one command and one login. Run claude mcp add --transport http linear https://mcp.linear.app/mcp in your terminal, then open a Claude Code session and run /mcp to complete Linear's OAuth flow in your browser. That is the whole setup: Linear hosts its MCP server itself, so there is nothing to install, no API key to paste for the default flow, and nothing to keep running locally. Once connected, Claude Code can read, create, and update Linear issues, projects, and comments directly from your session.

What the Linear MCP server is

MCP (Model Context Protocol) is the open standard AI tools use to talk to external systems. Linear ships an official remote MCP server, hosted at https://mcp.linear.app/mcp, that follows the authenticated remote MCP spec: your client connects over Streamable HTTP, authenticates with OAuth 2.1, and gets a set of tools scoped to your Linear workspace. Because Linear runs the server centrally, you never clone a repository, manage a Node process, or update anything when Linear adds capabilities.

As of August 2026, the server exposes tools for finding, creating, and updating issues, projects, and comments, and Linear's February 2026 update extended it to initiatives, initiative updates, project milestones, project updates, and project labels. In practice that covers the full loop a developer needs: pull an issue's description and discussion as context, do the work, move the status, and write a comment summarizing what changed.

Two endpoint details worth knowing before you start:

• Read-only variant. https://mcp.linear.app/mcp/readonly only ever exposes read tools. Use it when you want Claude to consult Linear but never write to it.
• SSE is deprecated. The older https://mcp.linear.app/sse endpoint remains as a fallback for clients that cannot speak Streamable HTTP. Claude Code can, so new setups should use the /mcp endpoint.

Step 1: Add the server

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

The name argument (linear here) is your local label for the server; any name works. The command prints an Added line when the configuration is written. By default this uses local scope, meaning the server is configured for you in the current project only. See the team section below for the project-wide option.

Step 2: Authenticate with /mcp

Start a Claude Code session and run:

/mcp

Select the Linear server and follow the sign-in. Your browser opens Linear's OAuth consent screen; approve it and the session shows the server as connected. Linear's flow uses OAuth 2.1 with dynamic client registration, so there is no client ID to configure. The grant acts as you: Claude can see and change what your Linear account can see and change, within the tools the server exposes.

Step 3: Verify the connection

claude mcp list

A healthy setup shows a Connected status next to the server name. If it shows Needs authentication, run /mcp again inside a session. You can inspect a single server with claude mcp get linear and remove it with claude mcp remove linear.

Step 4: Use it

Once connected, plain prompts work. Some patterns that hold up well:

• Issue as context: "Implement ENG-142. Read the issue and its comments first, then make the change." The session fetches the issue itself instead of you pasting it.
• Status and summary: "Mark ENG-142 In Review and comment with a summary of what changed."
• Filing from the terminal: "Create a bug in the Payments project titled 'Refund edge case crash' with repro steps from the stack trace above."
• Queue triage: "What are my assigned Linear issues? Which are small enough to knock out today?"

A useful convention: have Claude include the Linear issue ID in branch names and PR titles. Linear links the PR to the issue automatically, so status flows without extra prompting.

Authenticating with an API key instead

The OAuth flow is right for interactive use, but headless environments (CI jobs, containers, scripted sessions) cannot open a browser. Linear's MCP server also accepts direct bearer authentication: pass a Linear API key or OAuth token in the Authorization header when you add the server.

claude mcp add --transport http linear https://mcp.linear.app/mcp   --header "Authorization: Bearer YOUR_LINEAR_API_KEY"

Personal API keys are created in Linear under Settings, then Account, then Security & Access. As of August 2026 they support fine-grained permissions: full access, or restricted combinations like read plus create issues and create comments, optionally limited to specific teams. A key scoped to one team with read and comment permissions is a sensible floor for an agent that should consult Linear but not restructure it. Pair a restricted key with the readonly endpoint when you want belt and suspenders.

Sharing the setup with your team

The commands above configure your machine only. To make the server part of the repository, add it at project scope:

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

This writes a .mcp.json file at the project root. Commit it, and every teammate who runs Claude Code in that repository gets prompted to approve and use the same server, each authenticating with their own Linear account through /mcp. Never commit tokens into .mcp.json: the OAuth flow needs no stored secret, which is one reason to prefer it for anything shared. Claude Code asks each user to approve project-scoped servers before connecting, and unapproved servers show as pending in claude mcp list.

Anthropic also ships an official Linear plugin for Claude Code (installed with /plugin install linear@claude-plugins-official) that bundles the same connection with issue-workflow commands, if you prefer plugins over raw MCP configuration.

Troubleshooting

• OAuth errors like "invalid client" or a login loop. Remove and re-add the server, then retry /mcp. If it persists, revoke the Claude authorization in Linear's settings and authorize again. Switching to API-key auth with the bearer header sidesteps the browser flow entirely.
• Server shows Failed to connect. Check that the URL is exactly https://mcp.linear.app/mcp and the transport is http. If you configured JSON by hand, the entry needs a type field; streamable-http is accepted as an alias for http.
• Authentication asked for again. Tokens expire; running /mcp re-authenticates in place. Repeated prompts every session usually clear up after a remove, re-add, and fresh authorization.

Where AQ fits: the MCP connection is per-developer, Linear intake is per-team

Everything above wires Linear into one developer's Claude Code. Each teammate configures a client, authenticates, and drives the workflow by prompting: fetch the issue, do the work, move the status. That is exactly right for individual sessions. What it does not give a team is a shared starting point: the connection between "this issue should be worked by an agent" and "a session exists for it" still lives in whoever happens to type the prompt.

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. AQ connects to Linear at the workspace level instead of the client level: label an issue "ai-task" and a workspace appears for it in AQ, on its own isolated git worktree, visible to the team. Status syncs both ways, ownership follows the Linear assignee, and a human starts the agent in the workspace (nothing auto-launches). Inside that workspace, Claude Code runs as the real CLI under your own account, so the MCP setup from this guide still applies to the session itself: AQ handles issue-to-workspace, MCP handles issue-to-context.

The two compose rather than compete. If you are one developer, this page is all you need. If your team routes real Linear work through agents every day, see how the intake side works in AQ's Linear integration docs and the end-to-end flow in the Linear coding agent workflow guide.