---
title: How to connect Linear MCP to Claude Code
description: Run claude mcp add with Linear’s hosted URL and authenticate with /mcp. How to share it with a team, make it read-only, use an API key and fix errors.
canonical: https://mcp1.com/blog/linear-mcp-claude-code
last-updated: 2026-11-13
---

# How to connect Linear MCP to Claude Code

Run claude mcp add with Linear’s hosted URL and authenticate with /mcp. How to share it with a team, make it read-only, use an API key and fix errors.

![](https://avatars.githubusercontent.com/u/1297371?s=96&v=4)Eldad FuxFounder and CEO, Appwrite

 Terminal

$ claude mcp add --transport http linear mcp.linear.app/mcp

linearConnected

 Terminal

$ claude mcp add --transport http linear mcp.linear.app/mcp

linearConnected

To connect Linear to Claude Code, run `claude mcp add --transport http linear https://mcp.linear.app/mcp`, start Claude Code, run `/mcp` and choose Authenticate. Linear opens in your browser, you approve access for your workspace, and Claude Code can then find, create and update issues, projects and comments as you.

## How do I add the Linear MCP server to Claude Code?

Linear hosts its MCP server, so there is nothing to install. Three steps:

1. 1Add the server from your terminal:  
Terminal  
```  
claude mcp add --transport http linear https://mcp.linear.app/mcp  
```
2. 2Start `claude`, run `/mcp`, select `linear` and choose Authenticate. The server uses OAuth 2.1 with dynamic client registration, so there is no app to create and no key to paste.
3. 3Approve access in the browser tab that opens, then return to the terminal. Claude Code shows the server as connected and lists its tools.

Try it with a question you’d otherwise answer by clicking around: “Which of my issues in the current cycle are still in Todo?” or “File a bug in the Platform team for the failing login test, with the stack trace from this session.”

Use the Streamable HTTP URL

Linear also serves `https://mcp.linear.app/sse`, but its docs call that a deprecated fallback for clients without Streamable HTTP. Claude Code supports `--transport http`, so use the URL ending in `/mcp`.

## Which scope should I add it to?

`claude mcp add` defaults to local scope: the server works only in the directory you ran it from. Pick the scope by who should see it:

ScopeWhere it applies

`--scope local`

This project, only for you. The default. Stored in your user config, not in the repository.

`--scope user`

Every project on your machine, only for you.

`--scope project`

Everyone who opens the repository. Written to .mcp.json at its root, which you commit.

For Linear in every repository you work in, add it once at user scope:

Terminal

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

## How do I share the Linear server with my team?

Add it at project scope and commit `.mcp.json`. The file holds the URL and nothing secret, because each teammate signs in to Linear with their own account:

Terminal

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

Teammates approve the project server the first time Claude Code loads it, then run `/mcp` and authenticate. Each person’s calls carry their own Linear permissions, and Linear records changes under their name. For servers that only take a token, see [how to share an MCP server without sharing the API key](https://mcp1.com/blog/share-mcp-server-without-api-key).

## Can I connect Linear to Claude Code read-only?

Yes. Linear serves a second endpoint that only exposes read tools, so Claude Code can search and summarize issues but has no tool to change them:

Terminal

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

Linear’s docs give two other routes to the same result: request only the `read` OAuth scope on the main URL, or authenticate with an API key that has only the Read permission. For why the credential matters more than hiding tools, see [how to make an MCP server read-only](https://mcp1.com/blog/read-only-mcp-server).

## How do I use a Linear API key instead of OAuth?

Send it as a bearer token. Linear’s server accepts an API key or OAuth token in the `Authorization` header in place of the browser flow, which is what you want in CI or anywhere without a browser:

Terminal

```
claude mcp add --transport http linear https://mcp.linear.app/mcp \
  --header "Authorization: Bearer $LINEAR_API_KEY"
```

Create the key in Linear under Settings, Security & access, and give it only the permissions the job needs. Your shell expands `$LINEAR_API_KEY` before Claude Code saves the entry, so the key itself is stored in the config. Keep keyed entries at local or user scope, never in a committed `.mcp.json`. Running Claude Code in a pipeline is covered in [how to use MCP servers in CI and headless agents](https://mcp1.com/blog/mcp-in-ci-and-headless-agents).

## How do I stop Claude Code asking before every Linear call?

Claude Code names MCP tools `mcp__<server>__<tool>` and asks for permission before running one unless a rule allows it. To allow every tool from the Linear server, add the server name to the allow list in `.claude/settings.json`:

.claude/settings.json

```
{
  "permissions": {
    "allow": ["mcp__linear"]
  }
}
```

That includes write tools. If you’d rather approve writes one by one, allow single tools by their full name instead, and keep the read-only URL for people who never need to write.

## What if Linear doesn’t connect?

Check the entry first:

Terminal

```
claude mcp list
claude mcp get linear
```

Then match what you see:

- `linear` isn’t listed. You added it at local scope in another directory. Add it again here, or at user scope.
- It’s listed but not connected. Run `/mcp`, select it and authenticate again.
- You’re in the wrong Linear workspace. Each workspace needs its own authentication, and reconnecting doesn’t switch. Add a second entry with a different name, like `linear-ops`, and authenticate it against the other workspace.
- Linear’s docs suggest `rm -rf ~/.mcp-auth` for internal server errors. That folder belongs to the `mcp-remote` bridge, so it only helps clients that connect through it, not Claude Code’s native HTTP transport.

## Linear for the whole team, in every client

The steps above are per person and per client: each teammate adds Linear to Claude Code, again to Cursor, again to ChatGPT, and an admin has no single place to see what anyone’s agent did in Linear. MCP1 is a gateway that does it once. An admin installs [Linear](https://mcp1.com/servers/linear) in the workspace with one-click OAuth, puts it in a gateway with the other servers the team uses, and grants it to groups with full or read-only access. Each person connects their client once:

Terminal

```
claude mcp add --transport http mcp1 https://mcp1.com/mcp/<workspace>/<gateway>
```

Linear’s tools then appear as `linear__<tool>`, alongside GitHub, Sentry and the rest, and every call is checked against the person’s groups and recorded in the audit log. The [docs](https://mcp1.com/docs) cover gateways and groups, and the Individual plan is free to [start with](https://mcp1.com/signup).

## Common questions

### What can Claude Code do with the Linear MCP server?

Find, create and update Linear objects like issues, projects and comments, with your own permissions. Run /mcp and select linear to see the current tool list.

### Does the Linear MCP server work in Cursor and Codex too?

Yes. Point any client that supports remote MCP at https://mcp.linear.app/mcp. In Codex, run codex mcp add linear --url https://mcp.linear.app/mcp, then codex mcp login linear.

### Can Claude Code use two Linear workspaces?

Yes, as two server entries with different names, each authenticated against its own workspace. Reconnecting one entry does not switch it to another workspace.

### How do I remove the Linear server from Claude Code?

Run claude mcp remove linear. Add --scope user or --scope project if you added it at that scope, and revoke the app in Linear if you also want the grant gone.

Give your team one URL

Create a workspace, install your servers and share a gateway with a group. Free for individuals.

[Start with MCP1](https://mcp1.com/signup)[Read the docs](https://mcp1.com/docs)

## More from the blog

[What is an MCP gateway?An MCP gateway is one endpoint between MCP clients and many MCP servers. It signs people in, filters their tools, holds server credentials and logs every call.![](https://avatars.githubusercontent.com/u/1297371?s=96&v=4)Eldad FuxFounder and CEO, Appwrite](https://mcp1.com/blog/what-is-an-mcp-gateway)[ Destructive toolsgithub\_\_get\_file\_contentsAllowedgithub\_\_merge\_pull\_requestAsk firstsupabase\_\_execute\_sqlAsk firstgithub\_\_delete\_fileAdmin onlyHow to stop agents from running destructive MCP toolsDeny the destructive MCP tools an agent never needs, make the rest ask first, and give the server a credential that can’t delete. Then make writes undoable.![](https://avatars.githubusercontent.com/u/1297371?s=96&v=4)Eldad FuxFounder and CEO, Appwrite](https://mcp1.com/blog/stop-destructive-mcp-tools)

---

This is the markdown copy of https://mcp1.com/blog/linear-mcp-claude-code. Site index for agents: https://mcp1.com/llms.txt