Linear MCP Integration Server

Linear MCP 集成服务

此服务通过模型上下文协议（MCP）提供 Linear 集成功能。它允许 AI 模型使用 Linear 进行问题跟踪和项目管理。

功能

此服务通过 MCP 接口提供以下工具：

linear_create_issue

使用以下参数创建新的 Linear 问题：

• title（必填）：问题标题
• teamId（必填）：要在其中创建问题的团队 ID
• description（可选）：问题描述（支持 Markdown）
• priority（可选）：优先级（0-4）
• status（可选）：初始状态名称

linear_search_issues

搜索 Linear 问题，支持灵活筛选和分页：

• query（可选）：要在标题/描述中搜索的文本
• teamId（可选）：按团队筛选
• status（可选）：按状态筛选
• assigneeId（可选）：按负责人筛选
• priority（可选）：优先级（0-4）
• limit（可选，默认值：10）：每页最大结果数
• cursor（可选）：用于获取下一页的分页游标
• sortBy（可选，默认值：'updated'）：排序字段（'created'、'updated'、'priority'、'title'）
• sortDirection（可选，默认值：'desc'）：排序方向（'asc'、'desc'）

linear_sprint_issues

获取当前冲刺/迭代中的所有问题：

• teamId（必填）：要获取冲刺问题的团队 ID

linear_search_teams

搜索并获取 Linear 团队：

• query（可选）：要在团队名称中搜索的文本

linear_filter_sprint_issues

按状态筛选当前冲刺的问题，并自动筛选为当前用户负责的问题：

• teamId（必填）：要获取冲刺问题的团队 ID
• status（必填）：要筛选的状态（例如 "Pending Prod Release"）

linear_get_issue_details

获取特定问题的详细信息，包括完整描述、评论和元数据：

• issueId（必填）：要获取详细信息的问题 ID（例如 "DATA-1284"）

linear_bulk_update_status

一次性更新多个 Linear 问题的状态：

• issueIds（必填）：要更新的问题 ID 列表（例如 ["ENG-123", "DATA-456"]）
• targetStatus（必填）：要为所有问题设置的目标状态（例如 "In Progress"）

linear_manage_cycle

创建、更新或获取 Linear 周期（冲刺）的信息：

• action（必填）：要执行的操作："create"、"update"、"get" 或 "list"
• teamId（必填）：要管理周期的团队 ID
• cycleId（可选，update 和 get 操作必填）：周期 ID
• name（可选，create 操作必填）：周期名称
• startDate（可选，create 操作必填）：ISO 格式的开始日期（YYYY-MM-DD）
• endDate（可选，create 操作必填）：ISO 格式的结束日期（YYYY-MM-DD）
• description（可选）：周期描述

开发者设置

1. 从 Linear 的设置 > API 部分获取 Linear API 密钥
2. 在项目根目录中创建 .env 文件：

LINEAR_API_KEY=your_api_key_here

3. 安装依赖：

npm install

4. 启动服务：

# Development mode with auto-reload
npm run dev

# Production mode
npm start

# Build TypeScript
npm run build

# Run linter
npm run lint

# Run tests
npm run test

# Inspect MCP server
npm run inspect

技术细节

• 使用 TypeScript 和模型上下文协议 SDK 构建
• 使用 Linear SDK 进行 API 交互
• 包含错误处理、速率限制和连接管理
• 支持自动重新连接，并可配置重试次数
• 实现用于监控连接健康状况的心跳检测
• 在调试模式下提供详细日志
• 具有内存缓存系统，可提升性能
• 支持分页，以处理大量结果
• 为批量操作实现批处理

性能与可靠性

此服务包含全面的性能与可靠性功能：

缓存系统

• 对频繁访问的数据（团队、工作流状态）进行内存缓存
• 可配置缓存条目的 TTL（生存时间）
• 自动清理过期缓存条目
• 可在调试模式下查看缓存统计信息

错误处理

• 通过可配置的超时时间保护 API 调用
• 连接丢失时自动尝试重新连接
• 记录包含时间戳和上下文的详细错误日志
• 优雅地处理关闭并执行清理
• 通过心跳监控连接状态

性能优化

• 批量处理批量操作
• 支持对大型结果集进行分页
• 使用 Promise.all 并行处理并发操作
• 通过尽可能减少 API 调用来高效获取数据

依赖项

• @linear/sdk：Linear API 客户端
• @modelcontextprotocol/sdk：MCP 服务实现
• zod：运行时类型检查和验证
• dotenv：环境变量管理
• TypeScript 及相关开发工具

完整的依赖项列表请参阅 package.json。

Smithery 部署

此服务可以使用提供的配置文件部署到 Smithery.ai：

先决条件

• Smithery.ai 账号
• Linear API 密钥

部署步骤

1. 将此代码库添加到 Smithery，或认领现有服务
2. 访问 Deployments 标签页（仅限已通过身份验证的所有者）
3. 使用 Linear API 密钥配置部署
4. 部署服务

配置文件

代码库包含用于 Smithery 部署的两个必需文件：

1. Dockerfile：定义服务构建流程

   • 使用 Node.js 18 Alpine 作为基础镜像
   • 安装依赖项并构建 TypeScript 代码
   • 设置运行服务的命令

2. smithery.yaml：定义服务启动配置

   • 指定运行服务的命令
   • 定义必需的配置参数（Linear API 密钥）
   • 处理环境变量设置

本地测试

你可以使用 MCP Inspector 在本地测试 Smithery 配置：

# Build the Docker image
docker build -t linear-mcp-server .

# Run the container with your Linear API key
docker run -e LINEAR_API_KEY=your_api_key_here linear-mcp-server

# Or use the MCP Inspector
npm run inspect