Linear MCP (multi-workspace, PAT auth)

io.github.adelaidasofiaPublished by GitHub account adelaidasofiav0.3.2Updated Oct 24, 2026

Multi-workspace Linear MCP — PAT auth, 57 tools + 3 prompts, substrate enforcement, drop-in.

The publisher's own server: Linear

VerifiedSTDIODesktop onlyProductivity & WorkflowDeveloper Tools

Overview

AI-generated overview

Lets an assistant read and write Linear issues, projects, comments, and notifications across multiple workspaces using personal API keys.

What you can do
A local Linear MCP server exposing 57 tools and 3 prompts for teams, users, projects, initiatives, issues, cycles, milestones, labels, comments, documents, status updates, webhooks, notifications, attachments, issue relations, agent sessions, and search. Every tool accepts an optional workspace alias, so one install can route to several Linear workspaces. Write paths include server-side checks: a source-line requirement and duplicate detection on create, and an auth phrase for bulk issue changes. Destructive operations use a draft-then-confirm pattern.
When to use it
Useful when an assistant should work with Linear issues and projects directly, especially across more than one workspace or when OAuth-based setups are impractical. Also relevant for triage, weekly status drafting, and inbox sweeps through its prompts.
Requirements
Runs locally as a Python package (pipx or pip install) or a Claude Desktop bundle. Needs one Linear personal API key per workspace, supplied through environment variables such as LINEAR_PAT and per-workspace variables, plus workspace aliases and a primary workspace. Network access to the Linear API is required.
Before you install
Requires Linear personal API keys, which grant access to everything the owning user can see; store them in a permission-restricted file. Write tools create and update issues, projects, comments, and labels, and bulk changes require an explicit auth phrase. Webhook and attachment deletion are destructive but use draft-then-confirm. Tool calls are logged to a local audit file, and tokens are stripped from those records.

Installation

In SourceWeft

  1. Open Linear MCP (multi-workspace, PAT auth) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

linear-mcp

Multi-workspace Linear MCP server with Personal API Key auth. Drop-in replacement for the official OAuth-only Linear MCP at mcp.linear.app/mcp.

Why this exists. The official Linear MCP is OAuth-only and single-workspace per instance. PAT auth plus persistent token storage plus multi-workspace routing kills three failure modes:

  1. The OAuth flow is brittle across MCP client session boundaries — auth state expires when a session resumes mid-flow.
  2. The localhost callback fails in some setups, forcing fragile paste-back flows.
  3. One MCP instance per workspace doubles config + OAuth dances.

This server replaces both with one entry. One install, N workspaces, never an OAuth dance again.

Install

From PyPI

bash
pipx install adelaidasofia-linear-mcp

From source

bash
git clone https://github.com/adelaidasofia/linear-mcp ~/.claude/linear-mcpcd ~/.claude/linear-mcppip install -e .

Claude Desktop one-click

Download the latest .mcpb from Releases and double-click.

Configure

  1. Generate one Personal API Key per workspace at https://linear.app/settings/account/security. You must be logged into each workspace separately while generating the key for that workspace.

  2. Create ~/.claude/linear-mcp/admin.env (chmod 600):

bash
LINEAR_WORKSPACES=personal,workLINEAR_PRIMARY_WORKSPACE=personal
LINEAR_PAT_PERSONAL=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxLINEAR_PAT_WORK=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LINEAR_LABEL_PERSONAL=PersonalLINEAR_LABEL_WORK=Work

Aliases are arbitrary — name them whatever helps you route (acme,beta, team1,team2, home,client).

bash
chmod 600 ~/.claude/linear-mcp/admin.env
  1. Register in Claude Code (user scope, so it loads in every project):
bash
claude mcp add -s user linear-mcp python3 -m linear_mcp.server

Or, with pipx install:

bash
claude mcp add -s user linear-mcp linear-mcp
  1. Restart Claude Code. healthcheck should return ok: true per workspace.

Substrate-layer enforcement (v0.3)

Three server-side checks that protect issue quality without depending on any markdown rule file or client-side memory. Apply only to WRITE paths; reads stay unconstrained.

LayerWhat it doesBypass env var
[source:] first-line checksave_issue / save_project reject CREATE calls whose description (or project content) does not start with [source: <canonical-key>]. UPDATE calls (id passed) skip the check so legacy backfills remain unblocked.LINEAR_MCP_SKIP_SOURCE_CHECK=1
Idempotency checkBefore any CREATE, the server runs searchIssues / searchProjects for [source: <key>] and refuses to create a duplicate. The error names the existing identifier + UUID so the caller can update in place.LINEAR_MCP_SKIP_IDEMPOTENCY=1
auth_phrase on bulk_save_issuesbulk_save_issues now requires auth_phrase ∈ {"go", "yes do it", "confirmed", "execute", "go cancel", "go update"} (case-insensitive). Mass-modification surface stays explicit.(no bypass — surface the phrase to the operator)

Canonical-key examples:

  • [source: 🍄 Mycelium AI/📝 Meeting Notes/2026-05-22 - sync.md]
  • [source: ⚙️ Meta/Decisions/2026-05-23-merger-public-comms.md]
  • [source: linear-kickoff:sweep-myc-p1]
  • [source: ~/.claude/linear-mcp/BUILD_PROMPT_V03.md]

Fast issue execution

linear-exec is the short path for starting real work from a Linear issue. It resolves the issue, checks blocking relations, scans same-project siblings for obvious scope overlap, infers the repo when possible, and can create the standard claude-dev-worktree branch.

Dry-run a specific issue:

bash
linear-exec execute MYC-150 --workspace mycelium

Start the work after reviewing the preflight:

bash
linear-exec execute MYC-150 --workspace mycelium --repo memory-runtime-pro --go

Find the next unblocked P1 issue in a workspace:

bash
linear-exec sweep mycelium p1linear-exec sweep mycelium p1 --go --repo memory-runtime-pro

The command refuses to proceed when an upstream blocks relation is still incomplete unless --force is passed. --no-state-update and --no-worktree let agents use only the parts of the preflight they need.

Tool surface (v0.3 — 57 tools + 3 prompts)

Every tool takes an optional workspace parameter (the alias from LINEAR_WORKSPACES). Omit it to use LINEAR_PRIMARY_WORKSPACE.

Meta

ToolPurpose
list_workspacesShow configured workspaces and primary
healthcheckVerify each PAT + surface remaining rate-limit budget

Core entities

ToolPurpose
list_teams / get_teamTeams (with inline workflow states)
list_users / get_userUsers (me resolves to PAT owner)
list_projects / get_project / save_projectProjects (v0.3: save_project enforces [source:] on content + idempotency on CREATE)
list_initiatives / get_initiative / save_initiativeInitiatives
list_issues / get_issue / save_issue / bulk_save_issuesIssues (id or ONDE-123; bulk uses issueBatchUpdate; v0.3: save_issue enforces [source:] + idempotency on CREATE; bulk_save_issues requires auth_phrase)
list_cyclesCycles
list_milestones / get_milestone / save_milestoneProject milestones
list_issue_statuses / get_issue_statusWorkflow states
list_issue_labels / create_issue_labelLabels
list_comments / save_commentComments
list_documents / get_document / save_documentDocuments
save_status_updatePost a project status update

Webhooks (v0.2)

ToolPurpose
list_webhooks / get_webhookInspect subscriptions
create_webhook / update_webhookManage subscriptions
delete_webhookDestructive — draft+confirm

Notifications / inbox (v0.2)

ToolPurpose
list_notifications / get_notificationInbox read
notifications_unread_countTop-of-mind counter
mark_notification_read / mark_all_notifications_readTriage
archive_notificationSweep

Attachments (v0.2)

ToolPurpose
list_attachments / get_attachmentPer-issue reads
attachments_for_urlReverse lookup: which issues link to this URL?
link_url_to_issueAttach any URL to an issue
delete_attachmentDestructive — draft+confirm

Issue relations (v0.2)

ToolPurpose
list_issue_relationsThe blocks/duplicate/related graph
create_issue_relation / delete_issue_relationManage the graph

Agent sessions (v0.2)

ToolPurpose
list_agent_sessions / get_agent_sessionLinear's first-class agent surface
create_agent_session_on_issue / create_agent_session_on_commentSpawn

Search (v0.2 — replaces v0.1's broken search_documentation)

ToolPurpose
search_issues / search_documents / search_projectsFull-text per entity type
semantic_searchWorkspace-wide semantic across all entities

MCP prompts (v0.2)

Available as slash commands in MCP clients that surface prompts:

  • /triage-issue — full triage pass: classify, label, prioritize, assign, link duplicates
  • /project-status — draft a weekly status update from current Linear state
  • /inbox-sweep — sweep today's notifications, propose actions, archive what's handled

Multi-workspace usage

Switch workspaces inline:

list_teams(workspace="work")save_issue(workspace="personal", title="Ship", team_id="...")

Without workspace, the primary is used.

Auth

Linear PATs use header Authorization: <key> (no Bearer prefix). Each PAT is scoped to one workspace and grants access only to data the owning user can see. There is no shared org token.

Rate limit: 2500 requests/hour per token (verified against live API 2026-05-23). The server passes Linear's Retry-After header through on 429 and surfaces remaining budget via healthcheck.

Safety

Read tools and routine writes (create/update issues, comments, labels, status updates) pass through. Destructive ops (delete_webhook, delete_attachment) use the draft+confirm pattern: the first call stages the change and returns a draft_id + preview of what will happen; the second call (with confirm_draft_id) commits. Drafts expire after 1 hour (override with LINEAR_MCP_DRAFT_TTL_SECONDS).

Every tool call appends one JSONL line to ~/.claude/linear-mcp/audit.log (override with LINEAR_MCP_AUDIT_LOG_PATH, disable with LINEAR_MCP_AUDIT_LOG=false). Tokens are stripped from audit records.

healthcheck surfaces each PAT's remaining rate-limit budget (X-RateLimit-Requests-Remaining + X-Complexity-Remaining) per workspace, so agents can self-throttle without making a separate observability call.

Related MCPs

License

MIT.

Built by Adelaida Diaz-Roa. Full install or team version at diazroa.com.

Source: README.md at commit 8230fc2

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.2LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

Other Linear integrations

Linear

app.linearOfficial publisher

Linear's hosted MCP server, published by linear.app; credential required; Streamable HTTP.

Streamable HTTPWeb executableAuth
Productivity & WorkflowCredential requiredOct 24, 2026

Linear Programming Mcp

Published by GitHub account mrfentmen

A local stdio MCP server described as letting an assistant read, check, lint, scaffold and run code.

STDIODesktop only
Developer ToolsNot validated yetNov 8, 2026

Linear Mcp

Published by GitHub account mrfentmen

A local MCP server that lets an assistant query the Linear GraphQL API for the current user, teams, and issue search results.

STDIODesktop only
Productivity & WorkflowNot validated yetOct 24, 2026

Linear Project

org.openlyuseful

A scope-gated local MCP server for administering Linear projects, with optional read-only GitHub evidence and local Obsidian note adapters.

STDIODesktop only
Productivity & WorkflowNot validated yetOct 24, 2026

Linear Bootstrap

Published by GitHub account toolwright-adk

Local MCP server that turns natural-language descriptions into Linear projects with milestones, epics, issues and dependencies.

STDIODesktop only
Productivity & WorkflowNot validated yetOct 28, 2026