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

Hello, team leads and solo builders. This guide covers connecting Linear to Claude Code through the Linear MCP server, so your board and your code can live in one window.

By the end of this article, you will be able to add the Linear MCP to Claude Code with one command, sign in through your browser, confirm the connection really works, and use it to read and update your board without leaving the terminal. You will also know where to be careful, because this tool can change real issues.

When you’re coding, the work and the tracker live in two different windows. You finish a change. Then you 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 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. Because Linear hosts the server itself, connecting it takes one command and one browser sign-in. Most of this guide is about 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. 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. 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 gets the server, and in which projects:

# 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 the name you’re giving this server (you’ll see it again later in /mcp). The URL is Linear’s fixed endpoint. Copy both exactly. The --transport http flag matters because Linear uses Streamable HTTP, and its old /sse address is deprecated. 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. 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. There is no API key to create, copy, or paste.

Compare what you see to what you should see

Do all three checks before you rely on it.

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. 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 aim is to keep your hands on the code while the tracker stays current. Some prompts to start with:

• “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 causes, in the order they 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 fixes many of these.

Recap

The goal was to connect Linear to Claude Code and use it safely. The setup is one claude mcp add, one sign-in, and three checks. The main points:

• Linear hosts the MCP server, so there’s nothing to install. You add the https://mcp.linear.app/mcp URL with --transport http and pick a scope.
• Sign-in is OAuth through your browser. Claude acts as you, with the access your Linear account already has, and there’s no API key.
• Verify with claude mcp list, /mcp, and one real question before you trust it.
• The server can write to your tracker. Let it read freely, keep auto-accept off for writes, and review every change it proposes.
• Most failures are a missing sign-in or the wrong workspace. Check those first.

Because Linear hosts the server, the setup is small, so spend your attention on the fact that this tool can change your tracker. Let it read freely and make it ask before it writes.

I hope this writing helps you. Thanks for reading.