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.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
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
typestringRetrieve the current, previous, next, or all cycles. If no type is provided all cycles in the team will be returnedone of
current · previous · nextteamIdstringThe team ID
get_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
limitnumberThe number of results to return (Max is 250)default: 50
querystringAn optional search query
beforestringAn ID to end at
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtcreatedAtstringReturn 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
projectIdstringFilter by project ID
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
initiativeIdstringFilter by initiative ID
includeArchivedbooleanWhether to include archived documentsdefault: false
create_documentCreate a new document in Linear5 params
Create a new document in Linear
Parameters* required
iconstringThe icon of the document (for example, ":page_facing_up:")
colorstringThe color of the icon (hex color code)
titlestringThe title of the document
contentstringThe document content as Markdown
projectstringThe project name or ID to associate the document with
update_documentUpdate an existing Linear document6 params
Update an existing Linear document
Parameters* required
idstringThe document ID to update
iconstringThe icon of the document (for example, ":page_facing_up:")
colorstringThe color of the icon (hex color code)
titlestringThe new title of the document
contentstringThe new document content as Markdown
projectstringThe project name or ID to associate the document with
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
teamstringThe team name or ID to filter by
afterstringAn ID to start from
cyclestringThe cycle name or ID to filter by
labelstringA label name or ID to filter by
limitnumberThe number of results to return (Max is 250)default: 50
querystringSearch for content in the issue title or description
statestringThe state name or ID to filter by
beforestringAn ID to end at
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtprojectstringThe project name or ID to filter by
assigneestringThe assignee to filter by (User ID, name, email, or "me")
delegatestringAn agent name or ID to filter by
parentIdstringThe parent issue ID to filter by
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
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
includeArchivedbooleanWhether to include archived issues. Defaults to true.default: true
create_issueCreate a new Linear issue18 params
Create a new Linear issue
Parameters* required
teamstringThe team name or ID
cyclestringThe cycle name, number, or ID to add the issue to
linksarrayArray of link objects to attach to the issue. Each object must contain a valid `url` and a non-empty `title`.
statestringThe issue state type, name, or ID
titlestringThe issue title
blocksarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that this issue blocks. Creates blocking relations 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)
dueDatestringThe due date for the issue in ISO format
projectstringThe project name or ID to add the issue to
assigneestringThe user to assign (User ID, name, email, or "me")
delegatestringThe agent name, displayName, or ID to delegate
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.
blockedByarrayArray of issue IDs or identifiers (e.g., 'LIN-123') that block this issue. Creates blocking relations on issue creation.
milestonestringThe milestone 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.
descriptionstringThe issue description as Markdown
duplicateOfstringIssue ID or identifier (e.g., 'LIN-123') that this issue is a duplicate of. Creates a duplicate relation on issue creation.
update_issueUpdate an existing Linear issue19 params
Update an existing Linear issue
Parameters* required
idstringThe issue ID
cyclestringThe cycle name, number, or ID
linksarrayArray of link objects to attach to the issue. Each object must contain a valid `url` and a non-empty `title`.
statestringThe issue state type, name, or ID
titlestringThe issue title
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. Omit this field entirely to leave existing relations unchanged. Pass an empty array to remove all blocking relations.
labelsarrayArray of label names or IDs to set on the issue (you can use label names directly, no need to look up IDs)
dueDatestringThe due date for the issue in ISO format
projectstringThe project name or ID to add the issue to
assigneestringThe user to assign (User ID, name, email, or "me")
delegatestringThe agent name, displayName, or ID to delegate
estimatenumberThe numerical issue estimate value
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.
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 this field entirely to leave existing relations unchanged. Pass an empty array to remove all blocked-by relations.
milestonestringThe milestone name or ID
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 field entirely to leave existing relations unchanged. Pass an empty array to remove all related relations.
descriptionstringThe issue description as Markdown
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.
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
namestringFilter by label name
teamstringThe team name or ID
afterstringAn ID to start from
limitnumberThe number of results to return (Max is 250)default: 50
beforestringAn ID to end at
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtcreate_issue_labelCreate a new Linear issue label6 params
Create a new Linear issue label
Parameters* required
namestringThe name of the label
colorstringThe color of the label (hex color code)
teamIdstringThe team UUID. If not provided, the label will be created as a workspace label
isGroupbooleanWhether this is label group (cannot be applied to issues directly)default: false
parentIdstringThe parent label UUID, if this is a child of a label group
descriptionstringAn optional description of the label
list_projectsList projects in the user's Linear workspace12 params
List projects in the user's Linear workspace
Parameters* required
teamstringThe team name or ID to filter by
afterstringAn ID to start from
limitnumberThe number of results to return (Max is 250)default: 50
querystringSearch for content in the project name
statestringThe state name or ID to filter by
beforestringAn ID to end at
memberstringA team member to filter by (User ID, name, email, or "me")
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtcreatedAtstringReturn only projects created on or after this ISO-8601 date-time or duration. e.g. -P1D to get projects created in the last day
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
initiativestringThe initiative name or ID to filter by
includeArchivedbooleanWhether to include archived projectsdefault: false
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
iconstringThe icon of the project (for example, ":eagle:")
leadstringThe user to assign (User ID, name, email, or "me")
namestringA descriptive name of the project
teamstringThe team name or ID
colorstringA hex color for the project
statestringThe state of the project
labelsarrayArray of labels or IDs to set on the project
summarystringA concise plaintext summary of the project (max 255 chars)
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
initiativestringAn initiative ID or name to associate with the project
targetDatestringThe target date of the project in ISO format
descriptionstringThe full project description in Markdown format
update_projectUpdate an existing Linear project13 params
Update an existing Linear project
Parameters* required
idstringThe ID of the project to update
iconstringThe new icon of the project (for example, ":eagle:")
leadstringThe user to assign (User ID, name, email, or "me")
namestringThe new name of the project
colorstringThe new hex color for the project
statestringThe state of the project
labelsarrayArray of labels or IDs to set on the project
summarystringA concise plaintext summary of the project (max 255 chars)
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
targetDatestringThe target date of the project in ISO format
descriptionstringThe full project description in Markdown format
initiativesarrayArray of initiative IDs or names to associate with the project
list_project_labelsList available project labels in the Linear workspace5 params
List available project labels in the Linear workspace
Parameters* required
namestringFilter by label name
afterstringAn ID to start from
limitnumberThe number of results to return (Max is 250)default: 50
beforestringAn ID to end at
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
limitnumberThe number of results to return (Max is 250)default: 50
querystringAn optional search query
beforestringAn ID to end at
orderBystringThe order in which to return resultsone of
createdAt · updatedAtdefault: updatedAtcreatedAtstringReturn only teams created on or after this ISO-8601 date-time or duration. e.g. -P1D to get teams created in the last day
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
includeArchivedbooleanWhether to include archived teamsdefault: false
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
teamstringOptional team name or ID to filter members from
querystringOptional query to filter users by name or email
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
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
LINEAR_PAT*secretPersonal API Key from linear.app/settings/account/security
Categories
Registryactive
Packageadelaidasofia-linear-mcp
TransportSTDIO
AuthRequired
UpdatedMay 24, 2026
