Linear MCP 服务器

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

关于

这个 MCP（模型上下文协议）服务器为 AI 模型提供了与 Linear 问题跟踪功能交互的标准接口。

主要特性

• 使用官方 MCP SDK 为 Linear 实现标准的 MCP 协议
• 支持搜索问题、读取详细信息、更新和评论

开始使用

前提条件

• Node.js (v18 或更高版本)
• Linear API 密钥

安装

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

npm install

1. 在根目录下创建一个包含您的 Linear API 密钥的 .env 文件

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

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

2. 选择 "stdio" 作为传输类型

3. 输入以下命令：

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

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

与 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/                     # Source code
│   ├── effects/             # Effects implementation
│   │   ├── linear/          # Linear API effects
│   │   │   └── types/       # Linear type definitions
│   │   └── logging/         # Logging effects for safe logging with STDIO
│   ├── tools/               # MCP tools implementation
│   │   ├── types/           # Tool type definitions
│   │   └── utils/           # Tool utility functions
│   ├── utils/               # Utility modules
│   │   └── config/          # Configuration utilities
│   └── index.js             # Main entry point
├── docs/                    # Documentation
│   └── llm_context/         # Documentation for LLMs
├── logs/                    # Log files (created at runtime)
└── package.json             # Project configuration

可用工具

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 参数：

   {
     "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 客户端

• 实用程序：用于配置和通用功能的实用模块

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。