Linear MCP With Claude Code: Install and Use It

To use Linear from Claude Code, run claude mcp add --transport http linear-server https://mcp.linear.app/mcp in your terminal, then open Claude Code, type /mcp, choose the Linear server and sign in to Linear in your browser. Linear hosts and maintains the server, and it signs you in with OAuth 2.1, so there is no key to paste. Once connected, Claude Code can find, create and update issues, projects and comments, and work with initiatives, milestones and project updates. If you only want it to read, point it at https://mcp.linear.app/mcp/readonly instead.

The rest of this guide goes through the install, the sign-in, choosing between read-write and read-only, running it without a browser, and prompts worth trying. If MCP is new to you, what MCP is is the short version.

Step 1: install the server

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

That is the command in Linear’s own documentation↗ (opens in a new tab). linear-server is only the local name Claude Code uses; it also becomes part of each tool’s name in permission rules, so pick it once and keep it. The transport is streamable HTTP. Linear has deprecated its older SSE endpoint (https://mcp.linear.app/sse) and announced it is removing it, so if you copied a setup that uses /sse, change it to /mcp.

The command adds the server in Claude Code’s default local scope, which means this project only, for you only. Add --scope user to have Linear in every project on your machine, or --scope project to write it to a .mcp.json file your team can commit. With project scope each person still signs in with their own Linear account, and Claude Code asks for approval before using a server it found in that file.

Step 2: sign in

1. Open Claude Code in your project and type /mcp.
2. Choose linear-server. It will say it needs authentication; choose to authenticate.
3. Your browser opens on Linear. Sign in, check which workspace you are authorising and what access is requested, and approve.
4. Return to Claude Code. /mcp should now show the server connected with its tool count.

Linear’s server supports OAuth 2.1 with dynamic client registration, which is why Claude Code can sign in without you creating an app or copying a client ID. Claude Code’s documentation↗ (opens in a new tab) says it stores the resulting tokens securely and refreshes them automatically. You can also run the sign-in straight from a shell with claude mcp login linear-server. The steps behind that browser window, and what to look at on the consent screen, are in how MCP sign-in works.

Read-write or read-only?

Linear gives you two ways to keep the assistant read-only. You can connect to a separate endpoint that exposes only the read tools, or connect to the standard endpoint and grant only the read OAuth scope. The first is the simplest to set up in Claude Code:

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

Starting read-only for the first week is a sensible default. Claude Code can triage, summarise and draft, and you make the changes. When its suggestions are ones you would have made anyway, switch to the full endpoint. The reasoning is set out in MCP security best practices.

Running it without a browser

For CI jobs, remote boxes and other headless setups, Linear’s server also accepts a token directly in the Authorization header: either a Linear API key or an OAuth token. Linear notes you can create read-only API keys for this. Claude Code passes the header when you add the server:

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

Keep the key out of anything you commit. If you share the server in .mcp.json, Claude Code can expand environment variables there, so the file can reference a variable rather than hold the key. Alternatively, claude mcp login linear-server on a machine with no display prints the sign-in address for you to open elsewhere, then asks you to paste the redirect back.

What it can do

Linear describes the server as providing tools for finding, creating and updating objects such as issues, projects and comments. Since launch it has added tools↗ (opens in a new tab) to create and edit initiatives and initiative updates, project milestones and project updates, to manage project labels, to load images, and to load Linear resources from their URLs. In practice that means you can paste a Linear link into Claude Code and it can fetch what is behind it.

Tool names can change as Linear adds features, so rather than rely on a list copied from elsewhere, check what your connection exposes in /mcp after you sign in.

Prompts worth trying

Linear’s documentation includes example workflows for turning a roadmap document into projects, writing standup notes, investigating a bug, summarising a team’s cycle and planning an implementation. In Claude Code, the ones that pair best with code are:

• “Read ENG-231 and its comments, find the code involved, and propose a fix. Do not change the issue yet.”
• “List my issues in the current cycle that are In Progress, and tell me which ones have commits on this branch.”
• “Create an issue in the Platform team for each TODO in src/billing, with the file and line in the description.”
• “I have fixed ENG-231 in commit 7f3e21a. Comment with the commit and a one-line summary, and move it to Done.”

The last one is a write. Claude Code asks before an MCP tool call in Manual mode, which is a useful check here; recent versions start in auto mode instead. Once you are comfortable, pre-approve the read tools in your settings with rules↗ (opens in a new tab) of the form mcp__linear-server__<tool>, and keep writes on ask.

Things to watch

• Several workspaces. Linear’s documentation says each workspace needs its own authentication. Its example keeps them apart by giving each workspace a separate auth directory through the mcp-remote bridge, so plan one connection per workspace.
• It works as you. The OAuth sign-in authorises Claude Code on your Linear account, so what it changes is changed with your account. If your team wants to tell your edits from your assistant’s, agree a habit, such as a comment line, before you start.
• Big results fill the context window. Claude Code warns when a single MCP tool result passes 10,000 tokens and caps it at 25,000 by default. Ask for narrower queries, such as one team or one cycle, rather than raising the limit.
• Stale sign-ins. If the server stops responding after a long break, reconnect from /mcp, or use “Clear authentication” there and sign in again. Linear’s own troubleshooting also mentions clearing ~/.mcp-auth for clients that use the mcp-remote bridge.
• Enterprise sign-in. Workspaces on Okta can enable MCP enterprise-managed authentication so members are signed in through their identity provider; that is set up by an admin in Okta and Linear’s settings.

Removing it

claude mcp logout linear-server   # clear this machine's sign-in
claude mcp remove linear-server   # remove the server entirely

A simpler board, if that is what you need

Linear is built for product teams with cycles, projects and roadmaps, and if your team is happy there the MCP server makes it a good home for Claude Code too. If what you want is a simpler board your assistant works on as a member, with its own role on the board and a signed history of every change it makes, that is fenbs. The honest comparison is on fenbs vs Linear, and the Claude Code steps are on its integration page.