quickpromptco

Posted on Oct 20 Originally published at quickpromptco.com

How to Connect Linear MCP to Claude Code (Read-Only First, 1 Minute)

#ai #claude #mcp #productivity

You finish a fix in Claude Code, then switch to the browser to find the Linear issue, paste the description back into the terminal, and later go back again to write a comment and move it to Done. The agent that just did the work can’t see the ticket it was working on.

Linear MCP is Linear’s official hosted server. It lets Claude Code find, read, create, and update issues, projects, and comments in your workspace. There’s nothing to install: one command, an OAuth sign-in, and this guide starts you on Linear’s read-only endpoint so the agent can look before it can touch anything.

Tracking work in GitHub instead? See our GitHub MCP server setup.

Quick Start

Run this in your project folder:

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

Start Claude Code, run /mcp, pick linear, and approve access in the browser. Total time: about 1 minute. No API key to create or paste.

⚡ Copy This Prompt: Let Claude Code Install and Verify It For You

Skip the manual steps below and hand the whole job to the agent instead:

You have shell access and the `claude mcp` CLI on this machine. Connect Linear's official MCP server to Claude Code for this project in read-only mode and report back. Do not tell me it's done unless step 4 actually confirms it:

1. Run `claude mcp list`. If a linear entry already exists, show me its URL and stop instead of adding a second one.
2. Run:
   `claude mcp add --scope project --transport http linear https://mcp.linear.app/mcp/readonly`
3. Tell me to run `/mcp` in Claude Code, pick linear, and finish the Linear sign-in in my browser, choosing the workspace I want connected. Wait until I say it's done, then run `claude mcp list` and confirm linear shows Connected.
4. List the teams in my workspace and the 5 most recently updated issues assigned to me, with their IDs and status. Don't create or change anything.

Never ask me to paste an API key into this chat. If any step fails, give me the exact error and the command that produced it. Do not skip ahead.

The last step only reads, so you can see what Claude sees in your workspace before it can change anything.

What You’ll Need

Requirement	Why You Need It	Time
Claude Code installed	The client that calls the Linear tools	0 min
A Linear account	The server signs in as you and sees what your account can see	0 min
A browser on the same machine	For the one-time OAuth sign-in	0 min

Step-by-Step Setup

Prefer to do it by hand instead of delegating to the agent? Here’s the manual version.

Step 1 — Pick an endpoint

~10 sec

Linear hosts two addresses for the same server:

Endpoint	What It Allows
`https://mcp.linear.app/mcp/readonly`	Only read tools are exposed. Start here
`https://mcp.linear.app/mcp`	Read and write: create issues, update status, post comments

Linear’s own Claude Code example uses the read-write /mcp URL. Switching later is a remove and re-add, so there’s no cost to starting read-only.

Step 2 — Add the server

~10 sec

--scope project writes the entry to .mcp.json in your repo, so teammates who clone it get the same server. Each person still signs in with their own Linear account:

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

Real run, October 2026, read-only endpoint. Pending approval is normal for a project-scoped server: start claude, approve it, then sign in with /mcp.

Step 3 — Sign in with OAuth

~30 sec

Inside Claude Code, run /mcp, select linear, and choose Authenticate. Approve access in the browser for the workspace you want connected. Claude Code stores the token, so you do this once.

Read-only first: let Claude Code read your Linear issues before you let it change them.

What It Can Do

Job	Example Ask	Endpoint Needed
Find issues	“What’s assigned to me in the current cycle?”	Read-only
Read an issue in full	“Summarize LIN-123 and its comments, then find the code it’s about”	Read-only
Summarize a team’s work	“What did the web team finish last cycle?”	Read-only
Create issues and projects	“Turn this plan into a project with one issue per step”	Read-write
Update and comment	“Post what we fixed as a comment on LIN-123 and mark it Done”	Read-write

Verify It’s Actually Working

claude mcp list

✔ linear    https://mcp.linear.app/mcp/readonly (HTTP) – Connected

! linear    Needs authentication → run /mcp and sign in (Step 3)

✘ linear    Failed to connect → check the transport is http, not sse

Then ask for something only your workspace knows:

List my open Linear issues sorted by priority, with their IDs, and tell me which one has gone longest without an update.

If the IDs and titles match what you see in Linear, it’s working.

Common Mistakes to Avoid

Starting with write access. An agent that can create issues can also create forty of them from one vague plan. Use the read-only endpoint until you’ve seen how it reads your workspace.
Auto-approving write tools. Once you switch to /mcp, keep manual approval on for tools that create or update, so you see each change first. A Claude Code hook can enforce that.
Expecting reconnect to switch workspaces. Each sign-in is tied to one workspace. To use a second one, it needs its own separate sign-in; reconnecting the same entry won’t change it.
Using the old SSE URL. https://mcp.linear.app/sse is a deprecated fallback. Claude Code supports Streamable HTTP, so use /mcp or /mcp/readonly.
Pasting an API key into a chat. OAuth doesn’t need one. If you do need a key (see the Q&A), keep it in an environment variable.

Q&A

Is it free?

Yes. The MCP server comes with your Linear account at no extra cost.

How do I give it write access?

claude mcp remove linear --scope project, then add it again with https://mcp.linear.app/mcp and sign in again.

I get an internal server error when connecting.

Linear’s docs suggest clearing saved auth with rm -rf ~/.mcp-auth and trying again, and updating Node if you’re on an old version.

Can I use it in CI without a browser?

Yes. The server accepts a Linear API key or OAuth token in an Authorization: Bearer header. For read-only, create an API key with only the Read permission.

Does it work in Claude Desktop or claude.ai too?

Yes. Add Linear from Settings > Connectors there. That connection is separate from the one in Claude Code.

Official Resources

Linear MCP server docs — endpoints, clients, auth, FAQ
Linear + Claude — the connector for Claude Desktop and claude.ai
Claude Code MCP docs — claude mcp add, scopes, and OAuth with /mcp

Originally published at quickpromptco.com, where the guide is kept up to date.

DEV Community