Summary
Connects Claude to Linear's project tracking API using Personal Access Tokens instead of OAuth, solving the official server's session persistence issues and enabling true multi-workspace routing from a single MCP instance. Exposes 57 tools covering teams, issues, projects, cycles, webhooks, notifications, attachments, and full-text search across all entity types. Enforces source attribution at the substrate layer by requiring canonical keys in issue descriptions and blocking duplicate creates through automatic deduplication checks. Destructive operations like webhook deletion use a draft-then-confirm flow with one-hour expiry. Ships with three prompts for triage, project status drafting, and inbox sweeps. Reach for this when you manage issues across multiple Linear workspaces and want PAT-based auth that survives client restarts without re-dancing through OAuth callbacks.
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →
Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →
Tools
Public tool metadata for what this MCP can expose to an agent.
25 tools
list_commentsList comments for a specific Linear issue1 params
List comments for a specific Linear issue
Parameters* required
issueIdstringThe issue ID
create_commentCreate a comment on a specific Linear issue3 params
Create a comment on a specific Linear issue
Parameters* required
bodystringThe content of the comment as Markdown
issueIdstringThe issue ID
parentIdstringA parent comment ID to reply to
list_cyclesRetrieve cycles for a specific Linear team2 params
Retrieve cycles for a specific Linear team
Parameters* required
teamIdstringThe team ID
typestringRetrieve the current, previous, next, or all cycles. If no type is provided all cycles in the team will be returnedone of
current · previous · nextget_documentRetrieve a Linear document by ID or slug1 params
Retrieve a Linear document by ID or slug
Parameters* required
idstringThe document ID or slug
list_documentsList documents in the user's Linear workspace11 params
List documents in the user's Linear workspace
Parameters* required
afterstringAn ID to start from
beforestringAn ID to end at
createdAtstringReturn only documents created on or after this ISO-8601 date-time or duration. e.g. -P1D to get documents created in the last day
creatorIdstringFilter by creator ID
includeArchivedbooleanWhether to include archived documentsdefault: false
initiativeIdstringFilter by initiative ID
limitnumberThe number of results to return (Max is 250)default: 50
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtprojectIdstringFilter by project ID
querystringAn optional search query
updatedAtstringReturn only documents updated on or after this ISO-8601 date-time or duration. e.g. -P1D to get documents updated in the last day
create_documentCreate a new document in Linear5 params
Create a new document in Linear
Parameters* required
colorstringThe color of the icon (hex color code)
contentstringThe document content as Markdown
iconstringThe icon of the document (for example, ":page_facing_up:")
projectstringThe project name or ID to associate the document with
titlestringThe title of the document
update_documentUpdate an existing Linear document6 params
Update an existing Linear document
Parameters* required
colorstringThe color of the icon (hex color code)
contentstringThe new document content as Markdown
iconstringThe icon of the document (for example, ":page_facing_up:")
idstringThe document ID to update
projectstringThe project name or ID to associate the document with
titlestringThe new title of the document
get_issueRetrieve detailed information about an issue by ID, including attachments and git branch name2 params
Retrieve detailed information about an issue by ID, including attachments and git branch name
Parameters* required
idstringThe issue ID
includeRelationsbooleanWhether to include blocking, related, and duplicate relations in the responsedefault: false
list_issuesList issues in the user's Linear workspace. For my issues, use "me" as the assignee.16 params
List issues in the user's Linear workspace. For my issues, use "me" as the assignee.
Parameters* required
afterstringAn ID to start from
assigneestringThe assignee to filter by (User ID, name, email, or "me")
beforestringAn ID to end at
createdAtstringReturn only issues created on or after this ISO-8601 date-time or duration. e.g. -P1D to get issues created in the last day
cyclestringThe cycle name or ID to filter by
delegatestringAn agent name or ID to filter by
includeArchivedbooleanWhether to include archived issues. Defaults to true.default: true
labelstringA label name or ID to filter by
limitnumberThe number of results to return (Max is 250)default: 50
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtparentIdstringThe parent issue ID to filter by
projectstringThe project name or ID to filter by
querystringSearch for content in the issue title or description
statestringThe state name or ID to filter by
teamstringThe team name or ID to filter by
updatedAtstringReturn only issues updated on or after this ISO-8601 date-time or duration. e.g. -P1D to get issues updated in the last day
create_issueCreate a new Linear issue18 params
Create a new Linear issue
Parameters* required
assigneestringThe user to assign (User ID, name, email, or "me")
blockedByarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that block this issue. Creates blocking relations on issue creation.
blocksarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that this issue blocks. Creates blocking relations on issue creation.
cyclestringThe cycle name, number, or ID to add the issue to
delegatestringThe agent name, displayName, or ID to delegate
descriptionstringThe issue description as Markdown
dueDatestringThe due date for the issue in ISO format
duplicateOfstringIssue ID or identifier (e.g., 'LIN-123') that this issue is a duplicate of. Creates a duplicate relation on issue creation.
labelsarrayArray of label names or IDs to set on the issue (you can use label names directly, no need to look up IDs)
linksarrayArray of link objects to attach to the issue. Each object must contain a valid `url` and a non-empty `title`.
milestonestringThe milestone name or ID to add the issue to
parentIdstringThe parent issue ID, if this is a sub-issue
prioritynumberThe issue priority. 0 = No priority, 1 = Urgent, 2 = High, 3 = Normal, 4 = Low. Do not set this field unless explicitly requested.
projectstringThe project name or ID to add the issue to
relatedToarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that are related to this issue. Creates related relations on issue creation.
statestringThe issue state type, name, or ID
teamstringThe team name or ID
titlestringThe issue title
update_issueUpdate an existing Linear issue19 params
Update an existing Linear issue
Parameters* required
assigneestringThe user to assign (User ID, name, email, or "me")
blockedByarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that block this issue. WARNING: This REPLACES all existing blocked-by relations. You must include ALL blocking issues, not just new ones. Omit th...
blocksarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that this issue blocks. WARNING: This REPLACES all existing blocking relations. You must include ALL issues you want blocked, not just new ones....
cyclestringThe cycle name, number, or ID
delegatestringThe agent name, displayName, or ID to delegate
descriptionstringThe issue description as Markdown
dueDatestringThe due date for the issue in ISO format
duplicateOfstringIssue ID or identifier (e.g., 'LIN-123') this is a duplicate of. Replaces existing duplicate relation. Omit to leave unchanged, pass null to remove.
estimatenumberThe numerical issue estimate value
idstringThe issue ID
labelsarrayArray of label names or IDs to set on the issue (you can use label names directly, no need to look up IDs)
linksarrayArray of link objects to attach to the issue. Each object must contain a valid `url` and a non-empty `title`.
milestonestringThe milestone name or ID
parentIdstringThe parent issue ID, if this is a sub-issue
prioritynumberThe issue priority. 0 = No priority, 1 = Urgent, 2 = High, 3 = Normal, 4 = Low. Do not set this field unless explicitly requested.
projectstringThe project name or ID to add the issue to
relatedToarrayArray of issue IDs or identifiers (e.g., 'LIN-123') related to this issue. WARNING: This REPLACES all existing related relations. You must include ALL related issues, not just new ones. Omit this f...
statestringThe issue state type, name, or ID
titlestringThe issue title
list_issue_statusesList available issue statuses in a Linear team1 params
List available issue statuses in a Linear team
Parameters* required
teamstringThe team name or ID
get_issue_statusRetrieve detailed information about an issue status in Linear by name or ID3 params
Retrieve detailed information about an issue status in Linear by name or ID
Parameters* required
idstringThe ID of the issue status to retrieve
namestringThe name of the issue status to retrieve
teamstringThe team name or ID
list_issue_labelsList available issue labels in a Linear workspace or team6 params
List available issue labels in a Linear workspace or team
Parameters* required
afterstringAn ID to start from
beforestringAn ID to end at
limitnumberThe number of results to return (Max is 250)default: 50
namestringFilter by label name
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtteamstringThe team name or ID
create_issue_labelCreate a new Linear issue label6 params
Create a new Linear issue label
Parameters* required
colorstringThe color of the label (hex color code)
descriptionstringAn optional description of the label
isGroupbooleanWhether this is label group (cannot be applied to issues directly)default: false
namestringThe name of the label
parentIdstringThe parent label UUID, if this is a child of a label group
teamIdstringThe team UUID. If not provided, the label will be created as a workspace label
list_projectsList projects in the user's Linear workspace12 params
List projects in the user's Linear workspace
Parameters* required
afterstringAn ID to start from
beforestringAn ID to end at
createdAtstringReturn only projects created on or after this ISO-8601 date-time or duration. e.g. -P1D to get projects created in the last day
includeArchivedbooleanWhether to include archived projectsdefault: false
initiativestringThe initiative name or ID to filter by
limitnumberThe number of results to return (Max is 250)default: 50
memberstringA team member to filter by (User ID, name, email, or "me")
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtquerystringSearch for content in the project name
statestringThe state name or ID to filter by
teamstringThe team name or ID to filter by
updatedAtstringReturn only projects updated on or after this ISO-8601 date-time or duration. e.g. -P1D to get projects updated in the last day
get_projectRetrieve details of a specific project in Linear1 params
Retrieve details of a specific project in Linear
Parameters* required
querystringThe ID or name of the project to retrieve
create_projectCreate a new project in Linear13 params
Create a new project in Linear
Parameters* required
colorstringA hex color for the project
descriptionstringThe full project description in Markdown format
iconstringThe icon of the project (for example, ":eagle:")
initiativestringAn initiative ID or name to associate with the project
labelsarrayArray of labels or IDs to set on the project
leadstringThe user to assign (User ID, name, email, or "me")
namestringA descriptive name of the project
priorityintegerThe priority of the project. 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
startDatestringThe start date of the project in ISO format
statestringThe state of the project
summarystringA concise plaintext summary of the project (max 255 chars)
targetDatestringThe target date of the project in ISO format
teamstringThe team name or ID
update_projectUpdate an existing Linear project13 params
Update an existing Linear project
Parameters* required
colorstringThe new hex color for the project
descriptionstringThe full project description in Markdown format
iconstringThe new icon of the project (for example, ":eagle:")
idstringThe ID of the project to update
initiativesarrayArray of initiative IDs or names to associate with the project
labelsarrayArray of labels or IDs to set on the project
leadstringThe user to assign (User ID, name, email, or "me")
namestringThe new name of the project
priorityintegerThe priority of the project. 0 = No priority, 1 = Urgent, 2 = High, 3 = Medium, 4 = Low
startDatestringThe start date of the project in ISO format
statestringThe state of the project
summarystringA concise plaintext summary of the project (max 255 chars)
targetDatestringThe target date of the project in ISO format
list_project_labelsList available project labels in the Linear workspace5 params
List available project labels in the Linear workspace
Parameters* required
afterstringAn ID to start from
beforestringAn ID to end at
limitnumberThe number of results to return (Max is 250)default: 50
namestringFilter by label name
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtlist_teamsList teams in the user's Linear workspace8 params
List teams in the user's Linear workspace
Parameters* required
afterstringAn ID to start from
beforestringAn ID to end at
createdAtstringReturn only teams created on or after this ISO-8601 date-time or duration. e.g. -P1D to get teams created in the last day
includeArchivedbooleanWhether to include archived teamsdefault: false
limitnumberThe number of results to return (Max is 250)default: 50
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtquerystringAn optional search query
updatedAtstringReturn only teams updated on or after this ISO-8601 date-time or duration. e.g. -P1D to get teams updated in the last day
get_teamRetrieve details of a specific Linear team1 params
Retrieve details of a specific Linear team
Parameters* required
querystringThe UUID, key, or name of the team to retrieve
list_usersRetrieve users in the Linear workspace2 params
Retrieve users in the Linear workspace
Parameters* required
querystringOptional query to filter users by name or email
teamstringOptional team name or ID to filter members from
get_userRetrieve details of a specific Linear user1 params
Retrieve details of a specific Linear user
Parameters* required
querystringThe user to retrieve (User ID, name, email, or "me")
search_documentationSearch Linear's documentation to learn about features and usage2 params
Search Linear's documentation to learn about features and usage
Parameters* required
pagenumberThe page numberdefault: 0
querystringThe search query
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:
- The OAuth flow is brittle across MCP client session boundaries — auth state expires when a session resumes mid-flow.
- The localhost callback fails in some setups, forcing fragile paste-back flows.
- 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
pipx install adelaidasofia-linear-mcp
From source
git clone https://github.com/adelaidasofia/linear-mcp ~/.claude/linear-mcp
cd ~/.claude/linear-mcp
pip install -e .
Claude Desktop one-click
Download the latest .mcpb from Releases and double-click.
Configure
-
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.
-
Create
~/.claude/linear-mcp/admin.env(chmod 600):
LINEAR_WORKSPACES=personal,work
LINEAR_PRIMARY_WORKSPACE=personal
LINEAR_PAT_PERSONAL=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LINEAR_PAT_WORK=lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx
LINEAR_LABEL_PERSONAL=Personal
LINEAR_LABEL_WORK=Work
Aliases are arbitrary — name them whatever helps you route (acme,beta, team1,team2, home,client).
chmod 600 ~/.claude/linear-mcp/admin.env
- Register in Claude Code (user scope, so it loads in every project):
claude mcp add -s user linear-mcp python3 -m linear_mcp.server
Or, with pipx install:
claude mcp add -s user linear-mcp linear-mcp
- Restart Claude Code.
healthcheckshould returnok: trueper 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.
| Layer | What it does | Bypass env var |
|---|---|---|
[source:] first-line check | save_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 check | Before 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_issues | bulk_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:
linear-exec execute MYC-150 --workspace mycelium
Start the work after reviewing the preflight:
linear-exec execute MYC-150 --workspace mycelium --repo memory-runtime-pro --go
Find the next unblocked P1 issue in a workspace:
linear-exec sweep mycelium p1
linear-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
| Tool | Purpose |
|---|---|
list_workspaces | Show configured workspaces and primary |
healthcheck | Verify each PAT + surface remaining rate-limit budget |
Core entities
| Tool | Purpose |
|---|---|
list_teams / get_team | Teams (with inline workflow states) |
list_users / get_user | Users (me resolves to PAT owner) |
list_projects / get_project / save_project | Projects (v0.3: save_project enforces [source:] on content + idempotency on CREATE) |
list_initiatives / get_initiative / save_initiative | Initiatives |
list_issues / get_issue / save_issue / bulk_save_issues | Issues (id or ONDE-123; bulk uses issueBatchUpdate; v0.3: save_issue enforces [source:] + idempotency on CREATE; bulk_save_issues requires auth_phrase) |
list_cycles | Cycles |
list_milestones / get_milestone / save_milestone | Project milestones |
list_issue_statuses / get_issue_status | Workflow states |
list_issue_labels / create_issue_label | Labels |
list_comments / save_comment | Comments |
list_documents / get_document / save_document | Documents |
save_status_update | Post a project status update |
Webhooks (v0.2)
| Tool | Purpose |
|---|---|
list_webhooks / get_webhook | Inspect subscriptions |
create_webhook / update_webhook | Manage subscriptions |
delete_webhook | Destructive — draft+confirm |
Notifications / inbox (v0.2)
| Tool | Purpose |
|---|---|
list_notifications / get_notification | Inbox read |
notifications_unread_count | Top-of-mind counter |
mark_notification_read / mark_all_notifications_read | Triage |
archive_notification | Sweep |
Attachments (v0.2)
| Tool | Purpose |
|---|---|
list_attachments / get_attachment | Per-issue reads |
attachments_for_url | Reverse lookup: which issues link to this URL? |
link_url_to_issue | Attach any URL to an issue |
delete_attachment | Destructive — draft+confirm |
Issue relations (v0.2)
| Tool | Purpose |
|---|---|
list_issue_relations | The blocks/duplicate/related graph |
create_issue_relation / delete_issue_relation | Manage the graph |
Agent sessions (v0.2)
| Tool | Purpose |
|---|---|
list_agent_sessions / get_agent_session | Linear's first-class agent surface |
create_agent_session_on_issue / create_agent_session_on_comment | Spawn |
Search (v0.2 — replaces v0.1's broken search_documentation)
| Tool | Purpose |
|---|---|
search_issues / search_documents / search_projects | Full-text per entity type |
semantic_search | Workspace-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
- adelaidasofia/slack-mcp — multi-workspace Slack with draft+confirm
- adelaidasofia/whatsapp-mcp — WhatsApp via whatsmeow + vault export
- adelaidasofia/imessage-mcp — iMessage chat.db + vault export
- adelaidasofia/github-mcp — GitHub PR/issue/release
License
MIT.
Built by Adelaida Diaz-Roa. Full install or team version at diazroa.com.
Featured
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Notes, actions and memory. Without a meeting bot. First month 100% off.
Download for free →Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Configuration
LINEAR_PAT*secretPersonal API Key from linear.app/settings/account/security
Categories
Registryactive
Packageadelaidasofia-linear-mcp
TransportSTDIO
AuthRequired
UpdatedMay 24, 2026
