Linear MCP 服务器

这是一个用于 Linear 集成的 Node.js 实现的 MCP 服务器。

关于

此 MCP（模型上下文协议）服务器提供了标准化接口，使 AI 模型能够与 Linear 问题跟踪功能进行交互。

主要特性

• 使用官方 MCP SDK 实现了 Linear 的标准 MCP 协议
• 支持搜索问题、阅读详情、更新和评论

快速开始

先决条件

• Node.js（v18 或更高版本）
• Linear API 密钥

安装

1. 克隆仓库
2. 安装依赖项

npm install

3. 在根目录创建一个 .env 文件，并添加你的 Linear API 密钥

LINEAR_API_KEY=your_linear_api_key_here

运行服务器

启动服务器：

npm start

对于带有文件监视的开发模式：

just dev

对于带有调试日志的开发模式：

just debug

或者手动设置环境变量：

LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js

日志将写入 logs/mcp-linear.log 文件，以避免干扰 STDIO 传输。

使用 MCP Inspector

该服务器运行在 stdio 模式下，这意味着你可以使用 MCP Inspector 连接到它。

1. 在一个终端中启动服务器：

npm start

2. 访问基于 Web 的检查器：https://inspector.modelcontextprotocol.ai

3. 选择“stdio”作为传输类型

4. 输入以下命令：

node /path/to/mcp-linear/src/index.js

5. 点击“连接”以连接到正在运行的服务器

与 Claude Desktop 结合使用

在你的 Claude Desktop 配置文件（通常位于 ~/.config/Claude Desktop/claude_desktop_config.json）中添加以下内容：

{
  "mcp": {
    "servers": [
      {
        "name": "Linear",
        "command": "node /path/to/mcp-linear/src/index.js",
        "env": {
          "LINEAR_API_KEY": "your_linear_api_key_here"
        }
      }
    ]
  }
}

与 Cursor 结合使用

对于 Cursor，在你的设置中添加以下内容：

{
  "ai.mcp.servers": [
    {
      "name": "Linear",
      "command": "node /path/to/mcp-linear/src/index.js",
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  ]
}

测试集成

验证你的设置：

1. 在你的 Claude Desktop 或 Cursor 设置中配置 MCP 服务器
2. 重启你的应用程序
3. 提问：“搜索包含'bug'的 Linear 问题”
4. 助手应检测并使用 Linear MCP 服务器检索结果

项目结构

/
├── src/                     # 源代码
│   ├── effects/             # 效果实现
│   │   ├── linear/          # Linear API 效果
│   │   │   └── types/       # Linear 类型定义
│   │   └── logging/         # 用于安全日志记录的 STDIO 效果
│   ├── tools/               # MCP 工具实现
│   │   ├── types/           # 工具类型定义
│   │   └── utils/           # 工具实用函数
│   ├── utils/               # 实用模块
│   │   └── config/          # 配置实用工具
│   └── index.js             # 主入口点
├── docs/                    # 文档
│   └── llm_context/         # LLM 文档
├── logs/                    # 日志文件（运行时创建）
└── package.json             # 项目配置

可用工具

MCP 服务器暴露了以下工具：

• list_issues - 列出 Linear 问题（也称为票证），具有各种过滤选项（分配人、状态等）
• get_issue - 根据 ID 获取特定 Linear 问题的详细信息
• list_members - 列出 Linear 团队成员，可选按姓名过滤
• list_projects - 列出 Linear 项目，可选按团队、名称和归档状态过滤
• get_project - 获取特定 Linear 项目的详细信息，包括问题、成员等
• list_teams - 列出 Linear 团队及其成员、项目和问题的详细信息
• add_comment - 向特定 Linear 问题添加评论
• create_issue - 在 Linear 中创建新问题，具有可定制的标题、描述、优先级和分配人

为了兼容性，还提供以下工具别名：

• list_tickets - list_issues 的别名
• get_ticket - get_issue 的别名

故障排除

如果你遇到 Linear MCP 服务器的问题：

1. 检查你的 Linear API 密钥：确保你在 .env 文件或环境变量中设置了有效的 Linear API 密钥。Linear API 密钥应以 "linapi" 开头。

2. 启用调试日志：

   a. 当启动 MCP 服务器时：

   just debug
   # 或
   LOG_LEVEL=DEBUG NODE_ENV=development node src/index.js
   

   b. 在你的客户端配置（Claude Desktop、Cursor 等）中：

   "env": {
     "LINEAR_API_KEY": "your_linear_api_key_here",
     "LOG_LEVEL": "DEBUG"
   }
   

   c. 直接调用工具时，添加调试参数：

   {
     "debug": true
   }
   

3. 检查日志文件：查看 logs/mcp-linear.log 文件中的详细错误信息。

4. 验证 Linear API 访问：确保你的 Linear API 密钥具有适当的权限，并且可以直接访问 Linear API。

架构

应用程序遵循基于效果的架构：

• 效果：副作用操作被隔离在 effects 目录中：

  • linear：使用官方 Linear SDK 访问 Linear API
  • logging：不会干扰 STDIO 传输的安全日志记录

• 工具：使用效果进行副作用的 MCP 工具实现：

  • 每个工具都遵循一致的模式，使用 Zod 进行输入验证
  • 工具通过服务器暴露给 MCP 协议
  • 每个工具都可以通过 linear 效果访问 Linear 客户端

• 实用工具：配置和通用功能的实用模块

贡献

欢迎贡献！请随时提交拉取请求。

许可证

本项目根据 MIT 许可证发布 - 查看 LICENSE 文件获取详细信息。 </中文翻译>