Linear MCP Server

Linear MCP 服务

用于 Linear 问题跟踪和项目管理的模型上下文协议服务实现。此服务用于创建、更新和管理问题、周期、项目及其他 Linear 资源。

功能

• 使用官方 SDK 的 MCP 兼容服务
• 与 Linear API 无缝集成
• 使用 TypeScript 和 Zod schema 实现类型安全
• 全面的问题管理和跟踪
• 用户、团队和项目管理
• 周期和工作流状态处理
• 问题关联和依赖关系
• 评论和协作工具
• 流水线执行和多步骤工作流
• 高级错误处理和指标收集
• 可扩展的工具和流水线架构

工具

问题管理

• list_issues

  • 列出 Linear 中的问题
  • 输入：
    • teamId（string，可选）：要列出问题的团队 ID
    • first（number，可选）：要获取的问题数量（默认值：50）
    • projectId（string，可选）：按项目 ID 筛选问题
    • labelId（string，可选）：按标签 ID 筛选问题
    • stateId（string，可选）：按状态 ID 筛选问题
    • priority（number，可选）：按优先级筛选问题（0-4）
    • assigneeId（string，可选）：按受理人 ID 筛选问题
  • 返回：包含详细信息的 Linear 问题数组

• create_issue

  • 在 Linear 中创建新问题
  • 输入：
    • title（string）：问题标题
    • teamId（string）：团队 ID
    • description（string，可选）：问题描述
    • priority（number，可选）：问题优先级
    • assigneeId（string，可选）：受理人 ID
  • 返回：已创建问题的详细信息

• get_issue

  • 获取指定问题的详细信息
  • 输入：
    • id（string）：问题 ID
  • 返回：问题详细信息

• update_issue

  • 更新现有问题
  • 输入：
    • issueId（string）：要更新的问题 ID
    • title（string，可选）：新标题
    • description（string，可选）：新描述
    • projectId（string，可选）：新项目 ID（或设为 null 以移除）
    • stateId（string，可选）：新状态 ID
    • priority（number，可选）：新优先级
    • assigneeId（string，可选）：新受理人 ID（或设为 null 以取消分配）
    • parentId（string，可选）：新父问题 ID（或设为 null 以移除）
    • addLabelIds（string[]，可选）：要添加到问题的标签 ID
    • removeLabelIds（string[]，可选）：要从问题中移除的标签 ID
  • 返回：已更新问题的详细信息

问题关联

• add_issue_relation

  • 在两个问题之间创建关联
  • 输入：
    • issueId（string）：源问题的 ID
    • relatedIssueId（string）：目标问题的 ID
    • type（string）：关联类型（'related'、'blocks' 或 'duplicate'）
  • 返回：已创建关联的详细信息

• remove_issue_relation

  • 移除问题之间的关联
  • 输入：
    • relationId（string）：要移除的关联 ID
  • 返回：操作结果

• list_issue_relations

  • 列出指定问题的关联
  • 输入：
    • issueId（string）：问题 ID
    • first（number，可选）：要获取的关联数量
  • 返回：问题关联数组

评论

• list_issue_comments

  • 列出指定问题的评论
  • 输入：
    • issueId（string）：问题 ID
    • first（number，可选）：要获取的评论数量
  • 返回：评论数组

• create_comment

  • 向问题添加评论
  • 输入：
    • issueId（string）：问题 ID
    • body（string）：评论内容
  • 返回：已创建评论的详细信息

用户与团队管理

• list_users

  • 列出 Linear 中的用户
  • 输入：
    • first (number, optional)：要获取的用户数量（默认值：50）
    • includeArchived (boolean, optional)：是否包含已归档用户（默认值：false）
  • 返回：包含用户详细信息的数组

• get_user

  • 获取特定用户的详细信息
  • 输入：
    • id (string)：要获取的用户 ID
  • 返回：用户详细信息，包括姓名、显示名称、电子邮件和状态

• list_teams

  • 列出 Linear 中的团队
  • 输入：
    • first (number, optional)：要获取的团队数量（默认值：50）
    • includeArchived (boolean, optional)：是否包含已归档团队（默认值：false）
  • 返回：包含团队详细信息的数组

• get_team

  • 获取特定团队的详细信息
  • 输入：
    • id (string)：要获取的团队 ID
  • 返回：团队详细信息，包括名称、描述和键

周期

• list_cycles

  • 列出 Linear 中的周期
  • 输入：
    • first (number, optional)：要获取的周期数量
  • 返回：包含周期详细信息的数组

• get_cycle

  • 获取特定周期的详细信息
  • 输入：
    • id (string)：要获取的周期 ID
  • 返回：周期详细信息

• get_cycle_issues

  • 获取特定周期的议题
  • 输入：
    • cycleId (string)：周期 ID
    • first (number, optional)：要获取的议题数量
  • 返回：该周期中的议题数组

• explore_cycle_issue

  • 获取周期中某个议题的详细信息
  • 输入：
    • id (string)：要查看的议题 ID
  • 返回：议题详细信息

项目

• list_projects

  • 列出 Linear 中的项目
  • 输入：
    • first (number, optional)：要获取的项目数量
  • 返回：包含项目详细信息的数组

• get_project

  • 获取特定项目的详细信息
  • 输入：
    • id (string)：要获取的项目 ID
  • 返回：项目详细信息

标签

• list_labels

  • 列出 Linear 中的议题标签
  • 输入：
    • first (number, optional)：要获取的标签数量
  • 返回：包含标签详细信息的数组

• get_label

  • 获取特定标签的详细信息
  • 输入：
    • id (string)：要获取的标签 ID
  • 返回：标签详细信息

工作流状态

• list_workflow_states

  • 列出 Linear 中的工作流状态
  • 输入：
    • first (number, optional)：要获取的状态数量
    • teamId (string, optional)：按团队 ID 筛选状态
  • 返回：包含工作流状态详细信息的数组

• get_workflow_state

  • 获取特定工作流状态的详细信息
  • 输入：
    • id (string)：要获取的工作流状态 ID
  • 返回：工作流状态详细信息

流水线执行

• execute_pipeline
  • 有条件地执行一系列工具步骤，并转换数据。
  • 输入：
    • steps (array)：步骤列表，每个步骤包含 toolName、params、可选的 condition 和可选的 transform 函数。
    • context (object, optional)：执行上下文（requestId、timestamp、timeout、retryCount 等）。
  • 返回：流水线各步骤的结果数组。

流水线定义示例

{
  "steps": [
    { "toolName": "list_issues", "params": { "first": 1 } },
    { "toolName": "create_issue", "params": {}, "condition": "results => results && results.length > 0", "transform": "results => ({ title: 'Follow-up', teamId: results[0].teamId })" }
  ],
  "context": { "requestId": "abc123" }
}

错误处理

所有工具都以标准格式返回错误：

• code (string)：错误代码
• message (string)：错误消息
• retryable (boolean)：该错误是否可以重试
• details (object, optional)：其他详细信息
• suggestions (array, optional)：解决建议

指标与监控

• 跟踪每个工具的错误率和平均请求耗时
• 定期向 stderr 报告
• 可通过编程方式重置和检查指标

类型安全与可扩展性

• 所有工具架构均使用 Zod 定义，以进行运行时验证
• 通过扩展架构和处理程序即可轻松添加新工具
• 可使用 condition 和 transform 函数通过自定义逻辑组合流水线

用法示例：列出议题

curl -X POST http://localhost:3000/tool/list_issues \
  -H 'Content-Type: application/json' \
  -d '{ "teamId": "your-team-id", "first": 10 }'

用法示例：执行管道

{
  "steps": [
    { "toolName": "list_issues", "params": { "first": 2 } },
    { "toolName": "create_issue", "params": { "title": "Automated follow-up", "teamId": "team123" } }
  ]
}

---

如需了解更多详情，请参阅 Model Context Protocol 简介。

• 输入：

  • id（字符串）：要获取的问题 ID

• 返回：问题详情，包括标题、描述、状态和负责人信息

• list_issue_comments

  • 列出特定问题的评论
  • 输入：
    • issueId（字符串）：要获取评论的问题 ID
    • first（数字，可选）：要获取的评论数量（默认值：20）
  • 返回：评论数组，包含评论内容和作者信息

• create_comment

  • 在问题上创建新评论
  • 输入：
    • issueId（字符串）：要添加评论的问题 ID
    • body（字符串）：评论内容
  • 返回：已创建的评论详情

• execute_pipeline

  • 执行一系列 Linear 操作
  • 输入：
    • steps（数组）：管道步骤数组，每个步骤包含：
      • toolName（字符串）：要执行的工具名称
      • params（对象）：工具的参数
  • 返回：管道执行结果

设置

1. 获取 Linear API 密钥：

   • 登录 https://linear.app
   • 前往 Settings > API > Personal API keys
   • 点击“Create Key”
   • 为密钥命名（例如：“MCP Server”）
   • 复制生成的 API 密钥（该密钥仅显示一次）
   • 安全保存，以便在环境变量中使用

2. 安装依赖项：

npm install

3. 构建项目：

npm run build

与 Claude Desktop 配合使用

Node 版本

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": [
        "path/to/linear-mcp-server/build/index.js"
      ],
      "env": {
        "LINEAR_API_KEY": "<YOUR_LINEAR_API_KEY>"
      }
    }
  }
}

Docker 版本

{
  "mcpServers": {
    "linear": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "LINEAR_API_KEY",
        "mcp/linear"
      ],
      "env": {
        "LINEAR_API_KEY": "<YOUR_LINEAR_API_KEY>"
      }
    }
  }
}

Docker 构建

构建 Docker 镜像：

docker build -t mcp/linear -f src/linear/Dockerfile .

注意：

1. 将 <YOUR_LINEAR_API_KEY> 替换为你的 Linear API 密钥
2. 本地开发时，可以使用 Node 版本
3. 生产环境部署时，请使用 Docker 版本