Linear MCP 服务器

一个实现了 Model Context Protocol (MCP) 的服务器，通过标准化接口提供对 Linear 问题跟踪系统的访问。

特性

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

前提条件

• Bun 运行环境（v1.0.0 或更高版本）
• 拥有 API 访问权限的 Linear 账户

环境变量

LINEAR_API_KEY=your_api_key  # Your Linear API token

安装与设置

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",     // Expects status NAME (e.g., "In Progress"). Must be valid for the issue's team.
  "priority": "number",   // Expects 0 (None) to 4 (Low).
  "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 文件以获取详细信息。