linear-mcp

# 线性MCP <!-- mcp-name: io.github.adelaidasofia/linear-mcp --> 支持多工作区的线性MCP服务器，使用个人API密钥认证。可直接替换位于 `mcp.linear.app/mcp` 的官方OAuth-only线性MCP。 **为什么存在这个项目。** 官方线性MCP仅支持OAuth，并且每个实例只能对应一个工作区。使用PAT认证、持久化令牌存储和多工作区路由可以避免三种故障模式： 1. OAuth流程在MCP客户端会话边界处很脆弱 — 当会话在流程中途恢复时，认证状态会过期。 2. 在某些设置中，本地主机回调失败，强制使用脆弱的粘贴回流。 3. 每个工作区一个MCP实例会使配置和OAuth流程加倍。 该服务器可以用一个入口替换两者。一个安装，多工作区，不再需要OAuth流程。 ## 安装 ### 从PyPI ```bash pipx install adelaidasofia-linear-mcp ``` ### 从源码 ```bash git clone https://github.com/adelaidasofia/linear-mcp ~/.claude/linear-mcp cd ~/.claude/linear-mcp pip install -e . ``` ### Claude Desktop 一键安装 从 [Releases](https://github.com/adelaidasofia/linear-mcp/releases) 下载最新的 `.mcpb` 文件并双击。 ## 配置 1. 在 <https://linear.app/settings/account/security> 为每个工作区生成一个 **个人API密钥**。您必须单独登录每个工作区以生成该工作区的密钥。 2. 创建 `~/.claude/linear-mcp/admin.env` （chmod 600）： ```bash 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`）。 ```bash chmod 600 ~/.claude/linear-mcp/admin.env ``` 3. 在Claude Code中注册（用户范围，因此它会在每个项目中加载）： ```bash claude mcp add -s user linear-mcp python3 -m linear_mcp.server ``` 或者，使用 `pipx` 安装： ```bash claude mcp add -s user linear-mcp linear-mcp ``` 4. 重启Claude Code。`healthcheck` 应该返回每个工作区的 `ok: true`。 ## 基层强制（v0.3） 三种服务器端检查，保护问题质量，不依赖任何markdown规则文件或客户端内存。仅适用于WRITE路径；读取保持不受约束。 | 层级 | 功能 | 跳过环境变量 | |---|---|---| | `[source:]` 第一行检查 | `save_issue` / `save_project` 拒绝CREATE调用，其 `description` （或项目 `content`）不以 `[source: <canonical-key>]` 开头。UPDATE调用（传递 `id`）跳过检查，以便遗留数据回填保持畅通。 | `LINEAR_MCP_SKIP_SOURCE_CHECK=1` | | 幂等性检查 | 在任何CREATE之前，服务器运行 `searchIssues` / `searchProjects` 以获取 `[source: <key>]`，并拒绝创建重复项。错误名称现有标识 + 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]` ## 快速问题执行 `linear-exec` 是从线性问题开始实际工作的快捷方式。 它解决问题的同时，检查阻塞关系，扫描相同项目的兄弟节点以获取明显的范围重叠， 在可能的情况下推断仓库，并可以创建标准的 `claude-dev-worktree` 分支。 使用dry-run特定的问题： ```bash linear-exec execute MYC-150 --workspace mycelium ``` 在查看预检后开始工作： ```bash linear-exec execute MYC-150 --workspace mycelium --repo memory-runtime-pro --go ``` 在工作区中找到下一个未阻塞的P1问题： ```bash linear-exec sweep mycelium p1 linear-exec sweep mycelium p1 --go --repo memory-runtime-pro ``` 当上游 `blocks` 关系仍然不完整时，命令拒绝继续，除非传递 `--force`。 `--no-state-update` 和 `--no-worktree` 让代理仅使用他们需要的预检部分。 ## 工具表面（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` 在CREATE上强制执行 `[source:]` + 幂等性；`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` | 发布项目状态更新 | ### Webhooks（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` | blocks/duplicate/related 图 | | `create_issue_relation` / `delete_issue_relation` | 管理图 | ### 代理会话（v0.2） | 工具 | 目的 | |---|---| | `list_agent_sessions` / `get_agent_session` | 线性一流的代理表面 | | `create_agent_session_on_issue` / `create_agent_session_on_comment` | Spawn | ### 搜索（v0.2 — 替换v0.1的损坏 `search_documentation`） | 工具 | 目的 | |---|---| | `search_issues` / `search_documents` / `search_projects` | 每个实体类型的全文搜索 | | `semantic_search` | 跨所有实体的工作区范围语义搜索 | ### MCP提示（v0.2） 在MCP客户端中作为斜杠命令提供提示： - `/triage-issue` — 完整的分类传递：分类、标签、优先级、分配、链接重复项 - `/project-status` — 从当前线性状态起草每周状态更新 - `/inbox-sweep` — 清理今天的通知，提出行动建议，存档已处理的内容 ## 多工作区使用 内联切换工作区： ``` list_teams(workspace="work") save_issue(workspace="personal", title="Ship", team_id="...") ``` 如果没有 `workspace`，则使用主要工作区。 ## 认证 线性PAT使用头部 `Authorization: <key>` （无 `Bearer` 前缀）。每个PAT都限定在一个工作区内，并且仅授予所有者用户可见的数据的访问权限。没有共享的组织令牌。 速率限制：每个令牌每小时2500个请求（截至2026-05-23，对实时API进行验证）。服务器在429时传递线性的 `Retry-After` 头部，并在 `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`）按工作区， 因此代理可以自行限制而无需进行单独的可观察性调用。 ## 相关MCP - [adelaidasofia/slack-mcp](https://github.com/adelaidasofia/slack-mcp) — 多工作区Slack，具有草稿+确认 - [adelaidasofia/whatsapp-mcp](https://github.com/adelaidasofia/whatsapp-mcp) — 通过whatsmeow + vault导出WhatsApp - [adelaidasofia/imessage-mcp](https://github.com/adelaidasofia/imessage-mcp) — iMessage聊天.db + vault导出 - [adelaidasofia/github-mcp](https://github.com/adelaidasofia/github-mcp) — GitHub PR/问题/发布 ## 许可证 MIT。 --- 由Adelaida Diaz-Roa构建。在[diazroa.com](https://diazroa.com)上提供完整安装或团队版本。