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  # 您的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_m_ 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": [{ /* 过滤器 */ }],
    "or": [{ /* 过滤器 */ }],
    "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许可证 - 详情请参阅LICENSE文件。 </中文翻译>