Linear MCP 服务器

一个模型上下文协议 (MCP) 服务器实现，通过标准化接口提供对 Linear 问题跟踪系统的访问。

功能

• 创建带有标签支持的新问题和子问题
• 检索 Linear 项目列表
• 检索项目更新
• 创建带有健康状态的新项目更新
• 使用完整字段修改更新现有问题
• 通过验证删除问题
• 使用“me”关键字自我分配问题
• 使用 Linear 强大的过滤功能进行高级搜索
• 按周期过滤问题（当前、下一个、上一个或按 UUID 或编号的特定周期）
• 向问题添加带有 Markdown 支持的评论
• 通过 ID 或键查询 Linear 问题，并带有可选的关系
• 使用带有增强元数据的自定义查询搜索问题
• 使用 Linear 官方 SDK 进行类型安全操作
• 全面的错误处理
• 速率限制处理
• 清洁的数据转换
• 具有团队继承的父/子关系跟踪
• 标签管理和同步

前提条件

• Bun 运行时（v1.0.0 或更高版本）
• 具有 API 访问权限的 Linear 帐户

环境变量

LINEAR_API_KEY=your_api_key  # 您的 Linear API 令牌

安装和设置

1. 克隆存储库：

git clone [repository-url]
cd linear-mcp

2. 安装依赖项并构建：

bun install
bun run build

3. 配置 MCP 服务器：

编辑相应的配置文件：

macOS:

• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: 遗憾的是，尚不存在

在 mcpServers 对象下添加以下配置：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/absolute/path/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_api_key"
      }
    }
  }
}

4. 重新启动 MCP 服务器。

在 Cline 的 MCP 设置中，重新启动 MCP 服务器。 重新启动 Claude Desktop 以加载新的 MCP 服务器。

开发

运行开发服务器：

bun run dev

构建项目：

bun run build

可用的 MCP 工具

有关所有工具的详细使用示例，请参见 USAGE.md。

create_issue

创建一个新的 Linear 问题或子问题。

输入模式：

{
  "teamId": "string",     
  "title": "string",      
  "description": "string",
  "parentId": "string",   
  "status": "string",
  "priority": "number",   
  "assigneeId": "string | 'me'",
  "labelIds": ["string"]  
}

update_issue

更新现有的 Linear 问题。

输入模式：

{
  "issueId": "string",    
  "title": "string",
  "description": "string",
  "status": "string",     // 期望状态名称（例如，“进行中”）。 必须对问题团队有效。
  "priority": "number",   // 期望 0（无）到 4（低）。
  "assigneeId": "string | 'me'",
  "labelIds": ["string"],
  "cycleId": "string"
}

get_issue

获取有关特定 Linear 问题的详细信息，并带有可选的关系。

输入模式：

{
  "issueId": "string",
  "includeRelationships": "boolean"  
}

search_issues

使用查询字符串和高级过滤器搜索 Linear 问题。 支持 Linear 强大的过滤功能。

输入模式：

{
  "query": "string",
  "includeRelationships": "boolean",
  "filter": {
    "title": { "contains": "string", "eq": "string", ... },
    "description": { "contains": "string", "eq": "string", ... },
    "priority": { "gte": "number", "lt": "number", ... },
    "estimate": { "eq": "number", "in": ["number"], ... },
    "dueDate": { "lt": "string", "gt": "string", ... },
    "createdAt": { "gt": "P2W", "lt": "2024-01-01", ... },
    "updatedAt": { "gt": "P1M", ... },
    "completedAt": { "null": true, ... },
    "assignee": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "creator": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "team": { "id": { "eq": "string" }, "key": { "eq": "string" } },
    "state": { "type": { "eq": "started" }, "name": { "eq": "string" } },
    "labels": { "name": { "in": ["string"] }, "every": { "name": { "eq": "string" } } },
    "project": { "id": { "eq": "string" }, "name": { "contains": "string" } },
    "and": [{ /* filters */ }],
    "or": [{ /* filters */ }],
    "assignedTo": "string | 'me'",
    "createdBy": "string | 'me'"
  },
  "projectId": "string",
  "projectName": "string"
}

支持的比较器：

• 字符串字段：eq、neq、in、nin、contains、startsWith、endsWith（以及不区分大小写的变体）
• 数字字段：eq、neq、lt、lte、gt、gte、in、nin
• 日期字段：eq、neq、lt、lte、gt、gte（支持 ISO 8601 持续时间）

get_teams

获取 Linear 团队的列表，并带有可选的名称/键过滤。

输入模式：

{
  "nameFilter": "string"  
}

delete_issue

删除现有的 Linear 问题。

输入模式：

{
  "issueId": "string"
}

create_comment

在 Linear 问题上创建一个新评论。

输入模式：

{
  "issueId": "string",
  "body": "string"
}

get_projects

获取 Linear 项目的列表，并带有可选的名称过滤和分页。

输入模式：

{
  "nameFilter": "string",
  "includeArchived": "boolean",
  "first": "number",
  "after": "string"
}

get_project_updates

获取给定项目 ID 的项目更新，并带有可选的过滤参数。

输入模式：

{
  "projectId": "string",
  "includeArchived": "boolean",
  "first": "number",
  "after": "string",
  "createdAfter": "string",
  "createdBefore": "string",
  "userId": "string | 'me'",
  "health": "string"
}

create_project_update

为 Linear 项目创建一个新的更新。

输入模式：

{
  "projectId": "string",
  "body": "string",
  "health": "onTrack | atRisk | offTrack",
  "isDiffHidden": "boolean"
}

技术细节

• 使用严格模式的 TypeScript 构建
• 使用 Linear 的官方 SDK (@linear/sdk)
• 使用 MCP SDK (@modelcontextprotocol/sdk 1.4.0)
• 通过 API 令牌进行身份验证
• 全面的错误处理
• 速率限制注意事项
• Bun 运行时以提高性能
• 整个 ESM 模块
• Vite 构建系统
• 类型安全操作
• 数据清理功能：
  • 问题提及提取（ABC-123 格式）
  • 用户提及提取（@username 格式）
  • Markdown 内容清理
  • 针对 AI 上下文的内容优化
• 自我分配支持：
  • 自动当前用户解析
  • 在创建/更新操作中支持“me”关键字
  • 高效的用户 ID 缓存
• 高级搜索功能：
  • 使用 Linear API 进行全面过滤
  • 支持所有字段比较器
  • 关系过滤
  • 逻辑运算符（and、or）
  • 相对日期过滤
  • 按受让人/创建者过滤（包括自己）
  • 支持特定用户 ID
  • 按 ID 或名称进行项目过滤
  • 高效的查询优化
• 项目管理功能：
  • 具有过滤和分页的项目列表
  • 具有健康状态跟踪的项目更新创建
  • 具有过滤选项的项目更新检索

错误处理

服务器实现了全面的错误处理策略：

• 网络错误检测和适当的消息传递
• HTTP 状态代码处理
• 带有状态代码的详细错误消息
• 将错误详细信息记录到控制台
• 所有参数的输入验证
• 标签验证和同步
• 通过 MCP 协议进行安全错误传播
• 速率限制检测和处理
• 身份验证错误处理
• 无效查询处理
• 子问题的团队继承验证
• 用户解析验证
• 搜索过滤器验证

许可证

该项目已获得 MIT 许可证的许可 - 有关详细信息，请参见 LICENCE 文件。