Run your Linear board from Claude Code: set up the Linear MCP

When you’re coding, the work and the tracker live in two different windows. You finish a change, then tab over to Linear to move the issue, leave a comment, and open the next one, or you paste an issue’s description into chat so Claude has the context it’s missing. Both are friction, and both pull you out of the work.

The Linear MCP server closes that gap. It lets Claude Code read and write your Linear workspace directly, so you can say “start the next issue in my cycle” or “close this one and log what I changed” without leaving the terminal. And because Linear hosts the server itself, connecting it is small: one command, one browser sign-in. The work in this guide is less about setup and more about two things that matter more: what it can do to your tracker, and how to confirm it’s wired up before you trust it.

What the Linear MCP gives you, and where it stops

Once it’s connected, Claude can reach your Linear workspace through a small bridge called an MCP server, so instead of tabbing over to the app, you ask.

One command, then a sign-in

Linear runs the MCP server for you at a fixed web address. Claude Code connects to it as a client, you authorize it once through your browser, and from then on Claude can call it like any other tool.

Before you start

There’s nothing to install for the server itself. You only need:

• A Linear account with access to the workspace you want to reach. Whatever you can see and edit in Linear is what Claude will be able to see and edit.
• Claude Code, and confirm it actually runs before you start.

Open your terminal and check Claude Code is there:

claude --version

If that prints a version, you’re ready. If it doesn’t, install Claude Code first, then come back. This step is the same on macOS, Windows, and Linux: a hosted server has no platform-specific install.

One command to add it

In a terminal, add Linear as a remote HTTP server. Pick the scope that fits how you work; that flag decides who and which projects get the server:

# just you, in every project (the usual choice for solo work)
claude mcp add --transport http --scope user linear https://mcp.linear.app/mcp

# or: shared with your team via a checked-in .mcp.json
claude mcp add --transport http --scope project linear https://mcp.linear.app/mcp

Here linear is just the name you’re giving this server (you’ll see it again later in /mcp), and the URL is Linear’s fixed endpoint, so copy both exactly. That registers a server named linear pointing at Linear’s endpoint. The --transport http flag matters: Linear uses Streamable HTTP, and its old /sse address is deprecated, so if you have an older config pointing at https://mcp.linear.app/sse, re-add it with the /mcp URL above.

Authorize it through your browser

Adding the server doesn’t grant access; Linear still has to know it’s really you. Start Claude Code (claude) and run the built-in panel:

/mcp

Select linear and choose to authenticate. Here’s what happens, step by step: a browser tab opens to Linear’s sign-in (log in if you aren’t already); Linear shows a permissions screen listing what Claude Code can access; click the Authorize (or Connect) button; the tab tells you it’s done and you can close it; switch back to your terminal, where the connection is now live. If no browser opens automatically (common over SSH or on a headless Linux box) Claude Code prints a URL in the terminal; copy it into your browser manually to finish signing in. This is OAuth: you’re authorizing Claude Code to act in Linear as you, with exactly the permissions your account already has, and no API key to create, copy, or paste.

Compare what you see to what you should see

This is the part people skip and then wonder why nothing works. Do all three checks.

1. List your servers (in a normal terminal, or ask Claude Code to):

claude mcp list

2. Inside Claude Code, open the panel again:

/mcp

3. Actually use it. Ask in plain language:

List my open issues in the [your team] team, newest first, with their status.

Now line up your result against what it should be:

If all three match the middle column, you’re done. Claude can read and update your board now.

A few prompts to start with

The point isn’t to chat about Linear; it’s to keep your hands on the code while the tracker stays current. Some prompts that earn their keep:

• “What’s assigned to me in the current cycle? Order it by priority and give me a one-line summary of each.”
• “Create an issue in the Mobile team: ‘Receipt printing drops the last line on long orders.’ Add the steps to reproduce from what we just debugged, and label it bug.”
• “I’m starting ENG-412. Move it to In Progress and assign it to me.”
• “Summarise the comments on ENG-389 so I know where it stands before I pick it up.”
• “I just fixed this. Add a comment to the issue describing the change and move it to In Review.”

Tell Claude Code what you saw

The usual culprits, in the order they actually happen:

• “Needs authentication” / ✗ failed. You added the server but haven’t signed in, or the grant expired. Run /mcp, pick linear, and authenticate again.
• Connected, but the test returns nothing. You’re likely pointed at a different team or workspace than you think, or you have no issues matching the query. Name the team explicitly and try again.
• It connected before and now won’t. Your config may still point at the deprecated /sse URL. Remove it and re-add with the /mcp endpoint from Step 02: claude mcp remove linear, then the claude mcp add command again.
• Added it, but it’s not there in this project. You probably used the default local scope in a different directory. Re-add with --scope user so it follows you everywhere.
• Still stuck? Fully quit and reopen Claude Code. Remote servers reconnect on a fresh session, and a clean restart clears a surprising amount.

That’s the whole setup: one claude mcp add, one sign-in, three checks. Because Linear hosts the server, the setup is small, which means your attention belongs where it should, on the fact that this tool can change your tracker. Let it read freely, make it ask before it writes, and you get a project board that keeps itself current while you stay in the code.