How to connect Linear to Claude Code

A terminal with the claude mcp add command for Linear's MCP server, connected to a Linear team whose tasks Claude Code can find, create and update.

CRUX team · · Commands checked on · 6 min read

To connect Linear to Claude Code, add Linear's official MCP server with the command claude mcp add --transport http linear-server https://mcp.linear.app/mcp. Then run /mcp inside Claude Code and sign in to Linear in the browser. For one developer this is the shortest working way, and it needs no API key.

How do I connect Linear to Claude Code?

You need Claude Code installed and a Linear account in the workspace you work in. For this setup Linear's MCP documentation names no paid Linear plan; only its beta auto-connect for the Claude app names Business and Enterprise.

  1. Add the server. Run this in a terminal, in your project folder:
claude mcp add --transport http linear-server https://mcp.linear.app/mcp
  1. Sign in. Start Claude Code and run:
/mcp

Choose linear-server and follow the steps in the browser. Linear uses OAuth 2.1 with dynamic client registration, so you approve access on Linear's own page and paste no token. Claude Code stores the token and refreshes it. From a shell, claude mcp login linear-server starts the same sign-in.

By default Claude Code adds a server in the local scope, so it works only for you and only in the current project. The --scope user flag makes it available in all your projects, and --scope project writes it to a .mcp.json file in the project root for the team (Claude Code MCP documentation). Linear publishes no file for Claude Code, so this is the entry in Claude Code's own format:

{
  "mcpServers": {
    "linear-server": {
      "type": "http",
      "url": "https://mcp.linear.app/mcp"
    }
  }
}

If Claude Code should read Linear and change nothing, use Linear's read-only address https://mcp.linear.app/mcp/readonly in place of the default one.

Where a browser sign-in is impossible, Linear also accepts an API key in an Authorization: Bearer header. You create the key in Linear under "Security & access" in your account settings, if your workspace admin lets members create keys, and Claude Code sends headers through its --header flag.

How do I check that the connection works?

List the servers Claude Code knows about:

claude mcp list

linear-server should be in the list with ✔ Connected, or with ! Needs authentication before you sign in. For the details of this one server, run:

claude mcp get linear-server

Inside Claude Code, /mcp shows the server's status and whether you are signed in. Then ask "List the Linear tasks assigned to me" and compare the answer with Linear.

What can Claude Code do in Linear after that, and what can it not do?

Linear's documentation says the server has tools for finding, creating and updating tasks (Linear calls them issues), projects and comments, and that more will come.

The limits:

  • Linear's page does not publish the full list of tools or any limits specific to the MCP server. The /mcp menu in Claude Code shows the tools the server offers today.
  • With the default address Claude Code can write to Linear. Use the read-only address if you do not want that.
  • The server answers calls from a session that a person started. It does not start a session when a task changes status.

Claude Code or the Claude app?

Claude Code is the agent in your terminal, and claude mcp add connects it. In the Claude app (claude.ai, Claude Desktop and mobile) Linear comes as a connector: Linear's own Linear connector is in Anthropic's directory, and Anthropic's help page explains how to use connectors. You add it in the app's settings, with no command.

A connector you add in claude.ai also appears in Claude Code when you sign in to Claude Code with that claude.ai account. You still need claude mcp add when you use Claude Code with an API key, want the read-only address, or want a .mcp.json file for the team.

What changes when three or more people do this?

The connection itself still works. Each person signs in with their own Linear account, and --scope project writes the server to a .mcp.json file that the team keeps in the repository; Claude Code asks each person to approve that server the first time. The server does not cover how the team works together.

  • Nobody owns a status. A task sits in "In Review". Ryan, the developer, thinks Megan from QA starts the next step, and Megan waits for Ryan to ask. Nothing says who starts the step or who approves its result.
  • Each developer has their own prompts. Ryan asks Claude Code for a plan before any code. Another developer pastes the task text and asks for a fix. The reviewer cannot tell which of the two produced a pull request.
  • Answers stay in chat. Emily, the PM, answers Ryan's question about the export format in a chat message. Ryan pastes it into his session. The next session on the same task does not have that answer.
  • Nobody sees which session waits for whom. Three sessions are open on three laptops. One waits for Emily and one waits for a review. To learn this, you have to ask each person.

How does CRUX handle the team part?

We build CRUX, so this part is about our own product, and it is in beta.

What the agent needs to know about the project is already in Linear: the task, its parent and the decisions already on it. CRUX lets the agent read that, and each status in your workflow has its own instructions, so nobody writes a prompt. CRUX is the workflow layer between a team's tracker and the coding agents the team already uses.

Each team member connects their own Linear account through OAuth. A CRUX project is tied to one Linear team, and cycles become sprints when cycles are switched on for that team. Each status has an owner role. A person starts each step, approves the result at approval checkpoints, and moves the task to the next status. Each step posts its artifact as a comment on the task, so Emily's answer and the approved plan are in the place the next session reads.

When is the plain MCP server enough?

  • You work alone, or you are the only person on the team who uses a coding agent.
  • Two people who talk every day share the project and agree on who does what in one sentence.
  • You only need Claude Code to read tasks, create them and comment on them.
  • Your team already has shared prompts and an agreed order of steps, and they work.

In these cases Linear's server is the right tool and you need nothing else.

FAQ

Is there an official Linear MCP server?

Yes. Linear hosts it at https://mcp.linear.app/mcp and documents it at https://linear.app/docs/mcp.

Do I need a Linear API key?

No. The default sign-in is OAuth in the browser. An API key in an Authorization: Bearer header is an optional alternative.

Can I give Claude Code read-only access to Linear?

Yes. Use the address https://mcp.linear.app/mcp/readonly, or an API key that has only the Read permission.

Does every teammate have to sign in separately?

Yes. A shared .mcp.json file carries only the server's address. Each person runs /mcp and signs in with their own Linear account.

Try this on your own project. CRUX is free for one person, no card.

Start free

Next: How to connect Plane to Claude Code

All articles