mcp-linear

MCP 服务器，暴露 Linear 问题操作。独立运行——不依赖内置的 Claude Linear MCP。

问题通过其人类可读标识符（GOV-123）来引用。状态、团队、标签和指派者按名称给出；服务器将它们解析为 Linear UUID，并在名称不匹配时返回错误，列出有效选项。

工具

设置

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
cp .env.example .env
# Edit .env — set LINEAR_API_KEY

获取 API 密钥：Linear → 设置 → 安全与访问 → 个人 API 密钥。写操作需要具有写权限的密钥。

添加到 Claude Code

{
  "mcpServers": {
    "linear": {
      "command": "/Users/piuschungath/Workspace/mcp-linear/.venv/bin/mcp-linear",
      "env": { "LINEAR_API_KEY": "lin_api_..." }
    }
  }
}

测试

.venv/bin/pytest

所有 HTTP 请求均使用 respx 进行模拟。无需 API 密钥，也无需网络访问。

与 mcp-pr-assistant 配合使用

这两个服务器无需相互导入即可组合：使用 get_issue 获取工单，将其字段传递给 create_pr_from_ticket，然后通过 add_comment 将 PR URL 回传。

Schema 验证

src/mcp_linear/queries.py 中的 GraphQL 字段名已于 2026-08-21 针对实时 Linear API 验证，方法是针对真实工作区运行工具的实际查询字符串（而非其副本）。

已验证正确：

• Float! 问题编号比较器

• 通过 team { labels } 获取团队范围的标签

• 根 issueLabels 连接

• viewer.assignedIssues(orderBy: updatedAt)

• 三个变更发送的每个字段——IssueCreateInput、IssueUpdateInput 和 CommentCreateInput 均接受所使用的 teamId、title、description、stateId、assigneeId、priority、labelIds、issueId 和 body

发现并修复了一个差异：

• 全文搜索。 issueSearch 拒绝其 query 参数，因为该参数已弃用。搜索现在使用 searchIssues(term: ...)，它返回 IssueSearchPayload，其节点是 IssueSearchResult，而非 Issue——因此无法展开 IssueFields 片段。queries.py 声明了第二个片段 SearchFields，在该类型上具有相同的选择。内省确认 IssueSearchResult 携带 IssueFields 选择的每个字段。如果你更改了一个片段，请同时更改另一个。

有一件事尚未确认：

• 工作区标签。 根 issueLabels 连接可以解析，但它是仅返回工作区范围的标签，还是也返回属于其他团队的团队范围标签，尚未确定。标签解析首先查询团队自身的标签，因此团队标签总是优先于同名的的工作区标签。

在 Linear schema 更改后重新验证：

LINEAR_API_KEY=lin_api_... .venv/bin/python scripts/probe_schema.py <team-key> <issue-number> <issue-uuid>

它需要一个团队键、该团队上的一个现有问题编号以及该问题的 UUID（并会以交互方式提示一次，要求输入其首次探测打印的团队 UUID）。该探测是只读的：变更通过内省其输入类型来检查，绝不会写入你的跟踪器。

备注

• Linear 个人 API 密钥以 Authorization: <key> 形式发送，不带 Bearer 前缀。

• Linear 将大多数失败报告为 HTTP 200，并带有顶层 errors 数组，因此客户端检查响应体而不是状态码。

• 团队、状态、标签和用户元数据在服务器进程的整个生命周期内缓存。更改团队的工作流状态或标签后，请重启服务器。