Linear MCP — Use Cases, Install & Live Demo

Name: Linear MCP Server
Author: linear

Why use it

Key features

Official, remote-hosted — auth via mcp-remote OAuth, no token leaks
Full issue CRUD: create, update, assign, comment, move state
Query by cycle, team, assignee, label, project, or free-text
Respects your Linear workspace permissions — agent can't do what you can't

Live Demo

What it looks like in practice

linear.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.linear.app/sse"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.linear.app/sse"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.linear.app/sse"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.linear.app/sse"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "linear",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.linear.app/sse"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "linear": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "mcp-remote",
          "https://mcp.linear.app/sse"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add linear -- npx -y mcp-remote https://mcp.linear.app/sse

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Linear

How to triage a messy Linear backlog in 10 minutes

👤 Engineering managers, tech leads ⏱ ~15 min intermediate

When to use: Monday morning. The backlog has 200+ untriaged issues and planning is in an hour.

Prerequisites

Linear workspace access — OAuth through mcp-remote — first tool call opens browser to grant
Team slug (e.g. ENG) — Look at any issue identifier — the prefix is your team slug

Flow

Pull every untriaged issue for the team

List all ENG issues in state 'Triage' or with no priority set, created in the last 30 days. Return id, title, reporter, and description length.✓ Copied

→ Table of candidates with enough context to classify
Cluster by theme

Group these into 4-6 themes (bug / infra / onboarding / perf / etc.). For each cluster, propose a priority and suggested project.✓ Copied

→ Themed clusters with rationale
Apply the decisions

For each cluster, update the issues: set priority, add the matching label, and move to 'Backlog' state. Do NOT assign anyone.✓ Copied

→ N issues updated, confirmations logged

Outcome: A planning-ready backlog, grouped and prioritized, with an audit trail of every change the agent made.

Pitfalls

Agent mass-assigns issues to the wrong people based on 'who wrote similar code' — Explicitly tell it NOT to assign — assignment is a human call and should stay that way
Free-tier Linear rate-limits you after ~1500 requests/h — Batch updates with issueBatchUpdate when available; otherwise keep triage runs under 500 issues

Combine with: sentry · github

Generate a weekly cycle status report from Linear

👤 Engineering managers, PMs ⏱ ~10 min beginner

When to use: Friday afternoon, you need to write the weekly update for leadership.

Prerequisites

Active cycle in Linear — Linear > your team > Cycles — note the current cycle number

Flow

Pull cycle stats

For ENG cycle 47, list all issues grouped by state. Include completed-this-week, in-progress, blocked, and at-risk (no update in 3+ days).✓ Copied

→ Breakdown with counts and issue titles
Diff against last week

Compare to last week's snapshot [paste prior JSON]. What shipped, what regressed to earlier states, what's newly blocked?✓ Copied

→ Delta with narrative
Draft the report

Write a 1-page Markdown report: wins, in-flight, blockers, help-needed. Keep it honest — leadership reads between the lines.✓ Copied

→ Report ready to paste into Slack or Notion

Outcome: A polished cycle update in 10 minutes instead of 45.

Pitfalls

Completed issues without merged PRs look like progress but aren't — Combine with GitHub MCP — verify each 'Done' issue has a merged PR referenced

Combine with: github · notion

Auto-file Linear bugs from new Sentry issues

👤 On-call engineers ⏱ ~15 min intermediate

When to use: You want real-time error spikes in Sentry to become tracked bugs without manual copy-paste.

Prerequisites

Sentry MCP installed alongside Linear — See the sentry guide for setup
A dedicated Linear label like from-sentry — Linear > Settings > Labels — create once

Flow

Find new Sentry issues over threshold

Find Sentry issues first seen in the last 24h with >50 events in the web-prod project.✓ Copied

→ List with issue IDs and event counts
Check for duplicates in Linear

For each Sentry issue title, search Linear for existing issues with similar titles or containing the Sentry URL. Skip ones already filed.✓ Copied

→ Dedupe list — only genuinely new items
Create the Linear bugs

Create a Linear issue in ENG team for each new Sentry issue: title = Sentry title, description = stacktrace + link, priority = Urgent if >1000 events else High, label = from-sentry.✓ Copied

→ N issues created with links returned

Outcome: A clean Linear bug intake that never drops a production error on the floor.

Pitfalls

Same Sentry issue gets filed twice because titles drift slightly — Use the Sentry issue short-id (e.g. WEB-3a91) in the Linear title and dedupe on that substring

Combine with: sentry

Nudge stale issues in the current cycle

👤 Tech leads, scrum masters ⏱ ~5 min beginner

When to use: Mid-cycle check. Issues assigned for 5+ days with no state change are usually stuck.

Flow

Find the stale issues

List issues in the current ENG cycle that have been in 'In Progress' for 5+ days without a state change or comment.✓ Copied

→ List with assignee and days-stale
Post a gentle nudge comment

Add a comment on each: 'Quick check-in — still on track for this cycle, or do you need to break this down / get help?' Tag the assignee.✓ Copied

→ Comments posted, links returned
Escalate if ignored

In 48 hours, re-run. If still no update, DM me a list for 1:1 follow-up.✓ Copied

→ Escalation list for human follow-up

Outcome: Unblocked work without being the nagging manager every day.

Pitfalls

Comment spam if you run this hourly — Check if the agent has already commented in the last 3 days before posting again

Scaffold a Linear project from a Notion spec

👤 PMs, tech leads starting a new initiative ⏱ ~20 min intermediate

When to use: You have a written PRD and need to break it into trackable issues.

Prerequisites

Notion MCP installed — See notion guide
The PRD page URL — Copy from Notion

Flow

Read and summarize the spec

Read the Notion PRD at <URL> and list every discrete deliverable as a one-line description.✓ Copied

→ 15-40 candidate issues
Review and refine

Group these into 3-5 milestones. Flag any that need design, API, or DB work as separate issues.✓ Copied

→ Structured issue tree
Create the Linear project and issues

Create a Linear project named '<Spec title>' in ENG team. Create each milestone as a parent issue, with children as sub-issues. Link back to the Notion page in each description.✓ Copied

→ Project URL + issue count

Outcome: A fully-scaffolded Linear project in 20 minutes instead of 2 hours of manual ticket writing.

Pitfalls

Agent creates 80 issues when you wanted 20 — too granular — In step 2, explicitly cap: 'no more than 20 issues total, merge anything smaller than a day of work'

Combine with: notion

Combinations

Pair with other MCPs for X10 leverage

linear + sentry

Turn production error spikes into tracked Linear bugs automatically

Find new Sentry web-prod issues from the last 24h with >50 events. For each, create a Linear bug in ENG team labeled 'from-sentry', priority High, with the stacktrace in the description.✓ Copied

linear + github

Auto-link PRs to Linear issues and close issues when PRs merge

For every open PR in my repo, find the Linear issue ID in the title or branch name and add a reference comment on the Linear issue with the PR URL.✓ Copied

linear + notion

Post weekly cycle digests to a Notion database

Generate this week's ENG cycle status and create a page in the Notion 'Engineering Weekly' database with the full report.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
list_issues	team?, assignee?, state?, label?, cycle?, query?, limit?	Primary search — filter the stream	1 API call
get_issue	id	Fetch full context for a single issue	1 API call
create_issue	teamId, title, description?, priority?, labelIds?, assigneeId?, projectId?	File a new issue	1 API call
update_issue	id, stateId?, priority?, assigneeId?, labelIds?, title?, description?	Change state, priority, or assignment	1 API call
create_comment	issueId, body	Post a nudge or status note on an issue	1 API call
list_projects	teamId?	Discover active projects in a team	1 API call
list_cycles	teamId	Find active or recent cycles for a team	1 API call
list_teams		Discover teams in the workspace	1 API call

Cost & Limits

What this costs to run

API quota: 1500 req/h for OAuth apps, 120 req/min burst — generous for any real workflow
Tokens per call: 300–1500 tokens per issue depending on description/comments
Monetary: Free — Linear MCP is included in any Linear plan
Tip: Use list_issues with specific filters instead of pulling everything then filtering — cuts token cost 10x on large backlogs

Security

Permissions, secrets, blast radius

Minimum scopes: read write issues:create

Credential storage: OAuth via mcp-remote — tokens stored in ~/.mcp-auth/, refreshable without re-logging-in

Data egress: All calls to api.linear.app and mcp.linear.app

Never grant: admin

Troubleshooting

Common errors and fixes

OAuth browser popup doesn't open

Run npx -y mcp-remote https://mcp.linear.app/sse manually once — it'll print a URL you can paste into a browser

Verify: After auth, re-run your agent; token cached in ~/.mcp-auth/

403 on update_issue

Your Linear role lacks write access to that team. Ask a workspace admin to promote you or scope the agent to a team you own.

Issues returned but comments are missing

Comments are a separate query — use get_issue with include-comments, or list comments separately with the issue ID.

Can't find an issue you know exists

Check the team filter — issues in other teams aren't returned unless you pass team=null or specify that team.

Alternatives

Linear vs others

Alternative	When to use it instead	Tradeoff
Jira MCP	Your org is on Jira, not Linear	Heavier API, more states/fields to reason about — agents do worse on Jira out of the box
GitHub Issues (via GitHub MCP)	You want issues tightly coupled to code without a separate tool	Lose cycles, projects, and workflow states — GitHub Issues is simpler but less structured

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills