Linear MCP Server

Linear MCP 服务

概述

此项目实现了一个模型上下文协议（MCP）服务，作为 Claude 与 Linear 任务/问题管理系统之间的桥梁。它允许 Claude 通过以下工具与 Linear 交互：

1. get_ticket - 获取特定 Linear 工单的详细信息
2. get_my_issues - 列出分配给当前用户的问题，并按状态筛选
3. add_comment - 为 Linear 工单添加评论
4. create_issue - 在 Linear 中创建新问题
5. get_teams - 获取可供参考的团队列表

安装

无需直接安装。正确配置后，Claude 集成会自动下载并使用此软件包。

使用方法

1. 在你的 Linear 账户设置中获取 Linear API 密钥——点击“Personal API keys”下的“New API key”。

2. 按照下方说明在代码编辑器中配置 MCP 服务。

在 VS Code 中使用

一键安装：

将以下内容添加到你的 settings JSON 文件中：

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "linear_api_key",
        "description": "Linear API Key",
        "password": true
      }
    ],
    "servers": {
      "linear": {
        "command": "npx",
        "args": [
          "-y",
          "@larryhudson/linear-mcp-server"
        ],
        "env": {
          "LINEAR_API_KEY": "${input:linear_api_key}"
        }
      }
    }
  }
}

在 Cursor IDE 中使用

将以下内容添加到 MCP 配置 JSON 文件中：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@larryhudson/linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

在 Claude 桌面应用中使用

将以下内容添加到 MCP 配置 JSON 文件中：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": [
        "-y",
        "@larryhudson/linear-mcp-server"
      ],
      "env": {
        "LINEAR_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

在 Cline VS Code 扩展中使用

将以下内容添加到 MCP 配置 JSON 文件中：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@larryhudson/linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "<YOUR_API_KEY>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

环境变量

• LINEAR_API_KEY - 你的 Linear API 密钥（必需）

工作原理

此服务基于以下关键技术构建：

• 模型上下文协议（MCP） - 使 AI 助手能够与外部工具和 API 交互的框架
• Linear SDK - 用于与 Linear API 通信的客户端库
• Node.js - JavaScript 运行时环境
• Zod - 用于工具参数的类型验证库

主要功能

工单检索

• 获取全面的工单详情，包括状态、优先级、受派人和团队
• 获取完整描述和所有评论
• 处理包含嵌入图片的 Markdown 内容
• 下载并包含工单描述中的图片

问题列表

• 获取分配给当前用户的问题
• 按状态筛选（进行中、待办、已完成、已取消或全部）
• 返回格式化表格，其中包含每个问题的关键信息

添加评论

• 允许为现有工单添加评论
• 确认评论已成功创建

技术实现细节

1. 图像处理

   • 使用正则表达式从 Markdown 中提取图像 URL
   • 将图像下载到本地临时目录
   • 将图像转换为 base64，以便纳入 MCP 响应
   • 使用 URL 的 MD5 哈希创建唯一文件名

2. Linear API 集成

   • 使用 Linear API 密钥进行身份验证
   • 获取问题、工单、评论和用户信息
   • 将数据格式化为便于阅读的形式

3. 错误处理

   • 妥善处理 API 错误、工单缺失和下载失败
   • 向用户提供有意义的错误消息

运行服务

该服务通过标准输入/输出（stdio），使用 MCP 协议与 Claude 通信。它需要：

• Linear API 密钥（在代码中配置）
• Node.js 运行时环境
• package.json 中指定的依赖包

项目结构

这是一个相对简单的 Node.js 应用，只有一个主源文件（index.ts），用于定义 MCP 服务、工具及相关辅助函数。它使用 TypeScript 提供类型安全性并改善开发体验。

依赖项

• @modelcontextprotocol/sdk：MCP 核心实现
• @linear/sdk：Linear API 客户端
• dotenv：环境变量管理
• node-fetch：用于下载图像的 HTTP 客户端
• zod：工具参数的架构验证

局限性和潜在改进

• 对大型结果集的分页支持有限（目前最多支持 20 个问题）
• 可以改进对各种边缘情况的错误处理
• 图像下载功能可以采用更好的 MIME 类型检测
• 考虑添加更多用于管理问题的工具（更新状态、更改受托人等）
• 支持创建问题或添加评论时附加文件