Linear MCP (multi-workspace, PAT auth)

linear-mcp

支持多工作区的 Linear MCP 服务，使用个人 API 密钥进行身份验证。可直接替代官方仅支持 OAuth 的 Linear MCP：mcp.linear.app/mcp。

存在的原因。 官方 Linear MCP 仅支持 OAuth，且每个实例只能对应一个工作区。PAT 身份验证、持久化令牌存储和多工作区路由解决了三种常见故障：

1. OAuth 流程在 MCP 客户端会话边界之间不够可靠——会话在流程中途恢复时，身份验证状态会过期。
2. 在某些配置中，本地主机回调会失败，迫使用户采用脆弱的复制粘贴回传流程。
3. 每个工作区都部署一个 MCP 实例，会使配置和 OAuth 流程加倍。

此服务用一个入口替代两者。安装一次，支持 N 个工作区，从此不再需要 OAuth 流程。

安装

从 PyPI 安装

pipx install adelaidasofia-linear-mcp

从源代码安装

git clone https://github.com/adelaidasofia/linear-mcp ~/.claude/linear-mcp
cd ~/.claude/linear-mcp
pip install -e .

Claude Desktop 一键安装

从 Releases 下载最新的 .mcpb，然后双击。

配置

1. 在每个工作区中生成一个个人 API 密钥，网址为 https://linear.app/settings/account/security。为某个工作区生成密钥时，必须单独登录该工作区。

2. 创建 ~/.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

别名可以任意设置——选择方便你路由的名称（acme,beta、team1,team2、home,client）。

chmod 600 ~/.claude/linear-mcp/admin.env

3. 在 Claude Code 中注册（用户范围，因此每个项目都会加载）：

claude mcp add -s user linear-mcp python3 -m linear_mcp.server

或者，使用 pipx 安装：

claude mcp add -s user linear-mcp linear-mcp

4. 重启 Claude Code。每个工作区的 healthcheck 都应返回 ok: true。

基础层强制检查（v0.3）

三项服务端检查，可在不依赖任何 Markdown 规则文件或客户端记忆的情况下保障 issue 质量。仅应用于写入路径；读取不受限制。

层	功能	绕过环境变量
[source:] 首行检查	save_issue / save_project 会拒绝 description（或项目的 content）未以 [source: <canonical-key>] 开头的 CREATE 调用。UPDATE 调用（传入 id）会跳过检查，以免阻碍旧数据回填。	LINEAR_MCP_SKIP_SOURCE_CHECK=1
幂等性检查	每次 CREATE 前，服务都会对 [source: <key>] 执行 searchIssues / searchProjects，并拒绝创建重复项。错误信息会列出已有标识符和 UUID，便于调用方原位更新。	LINEAR_MCP_SKIP_IDEMPOTENCY=1
bulk_save_issues 的 auth_phrase	现在，bulk_save_issues 要求 auth_phrase ∈ {"go", "yes do it", "confirmed", "execute", "go cancel", "go update"}（不区分大小写）。批量修改操作始终明确可见。	（不可绕过——向操作人员显示该短语）

规范键示例：

• [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]

快速执行 issue

linear-exec 是从 Linear issue 开始实际工作的快捷方式。 它会解析 issue、检查阻塞关系、扫描同一项目中的同级 issue 以发现明显的范围重叠，在可能时推断仓库，并可创建标准的 claude-dev-worktree 分支。

对指定 issue 执行试运行：

linear-exec execute MYC-150 --workspace mycelium

检查预检结果后开始工作：

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

查找工作区中下一个未受阻的 P1 issue：

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

如果上游 blocks 关系尚未完成，该命令会拒绝继续，除非传入 --force。--no-state-update 和 --no-worktree 允许 Agent 仅使用所需的预检功能。

工具概览（v0.3——57 个工具 + 3 个提示词）

每个工具都接受可选的 workspace 参数（来自 LINEAR_WORKSPACES 的别名）。省略该参数时，将使用 LINEAR_PRIMARY_WORKSPACE。

元信息

工具	用途
list_workspaces	显示已配置的工作区和主工作区
healthcheck	验证每个 PAT，并显示剩余速率限制额度

核心实体

工具	用途
list_teams / get_team	团队（包含内联工作流状态）
list_users / get_user	用户（me 会解析为 PAT 所有者）
list_projects / get_project / save_project	项目（v0.3：save_project 要求 content 包含 [source:]，并确保 CREATE 操作具备幂等性）
list_initiatives / get_initiative / save_initiative	计划
list_issues / get_issue / save_issue / bulk_save_issues	问题（可使用 id 或 ONDE-123；批量操作使用 issueBatchUpdate；v0.3：save_issue 要求包含 [source:]，并确保 CREATE 操作具备幂等性；bulk_save_issues 需要 auth_phrase）
list_cycles	周期
list_milestones / get_milestone / save_milestone	项目里程碑
list_issue_statuses / get_issue_status	工作流状态
list_issue_labels / create_issue_label	标签
list_comments / save_comment	评论
list_documents / get_document / save_document	文档
save_status_update	发布项目状态更新

Webhook（v0.2）

工具	用途
list_webhooks / get_webhook	查看订阅
create_webhook / update_webhook	管理订阅
delete_webhook	具有破坏性的操作——起草并确认

通知 / 收件箱（v0.2）

工具	用途
list_notifications / get_notification	查看收件箱
notifications_unread_count	未读计数
mark_notification_read / mark_all_notifications_read	分类处理
archive_notification	清理

附件（v0.2）

工具	用途
list_attachments / get_attachment	按问题查看
attachments_for_url	反向查找：哪些问题链接到此 URL？
link_url_to_issue	将任意 URL 附加到问题
delete_attachment	具有破坏性的操作——起草并确认

问题关联（v0.2）

工具	用途
list_issue_relations	阻塞 / 重复 / 相关关系图
create_issue_relation / delete_issue_relation	管理关系图

Agent 会话（v0.2）

工具	用途
list_agent_sessions / get_agent_session	Linear 的一等 Agent 接口
create_agent_session_on_issue / create_agent_session_on_comment	启动

搜索（v0.2 — 替代 v0.1 中失效的 search_documentation）

工具	用途
search_issues / search_documents / search_projects	按实体类型进行全文搜索
semantic_search	在整个工作区内跨所有实体进行语义搜索

MCP 提示词（v0.2）

在支持提示词的 MCP 客户端中，可通过斜杠命令使用：

• /triage-issue — 完整的问题分类处理：分类、添加标签、确定优先级、分配负责人、关联重复项
• /project-status — 根据当前 Linear 状态起草每周状态更新
• /inbox-sweep — 清理今天的通知，提出操作建议，并归档已处理的通知

多工作区用法

在行内切换工作区：

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

如果未指定 workspace，则使用主工作区。

身份验证

Linear PAT 使用请求头 Authorization: <key>（不带 Bearer 前缀）。每个 PAT 仅限一个工作区，并且只能访问该 PAT 所有者可见的数据。不存在共享的组织令牌。

速率限制：每个令牌每小时 2500 次请求（已于 2026-05-23 对照实时 API 验证）。服务会透传 Linear 的 Retry-After 请求头（适用于 429 响应），并通过 healthcheck 显示剩余额度。

安全性

读取工具和常规写入（创建／更新问题、评论、标签、状态更新）会直接执行。破坏性操作（delete_webhook、delete_attachment）采用草稿+确认模式：首次调用会暂存更改，并返回 draft_id 和操作预览；第二次调用（附带 confirm_draft_id）才会提交。草稿会在 1 小时后过期（可通过 LINEAR_MCP_DRAFT_TTL_SECONDS 覆盖）。

每次工具调用都会向 ~/.claude/linear-mcp/audit.log 追加一行 JSONL 记录（可通过 LINEAR_MCP_AUDIT_LOG_PATH 覆盖；将 LINEAR_MCP_AUDIT_LOG=false 可禁用）。审计记录中会剔除令牌。

healthcheck 会按工作区显示每个 PAT 的剩余速率限制额度（X-RateLimit-Requests-Remaining + X-Complexity-Remaining），让 Agent 无需单独进行可观测性调用即可自行控制调用频率。

相关 MCP

• adelaidasofia/slack-mcp — 支持多工作区的 Slack，采用草稿+确认模式
• adelaidasofia/whatsapp-mcp — 通过 whatsmeow 使用 WhatsApp，并支持保管库导出
• adelaidasofia/imessage-mcp — iMessage chat.db，并支持保管库导出
• adelaidasofia/github-mcp — GitHub PR／问题／发布

许可证

MIT。

---

由 Adelaida Diaz-Roa 构建。完整安装版或团队版请访问 diazroa.com。