线性-MCP

Name: 线性-MCP
Author: locomotive-agency

作者：locomotive-agency9 星标更新：2025-10-30

安装使用来源：spider==github.com

项目介绍

Linear MCP Server - 生产级

适用于Linear.app的企业级MCP服务器，具有企业级弹性、性能优化和清晰架构。

基于cline/linear-mcp构建，增加了10项主要改进和5,116行生产代码。

✨ 关键改进

🛡️ 企业级弹性

✅ 速率限制 - 永不超出Linear API限制（每小时1000次，每分钟100次）
✅ 自动重试 - 对于瞬时失败，成功率超过90%，采用指数退避策略
✅ 实时监控 - 实时配额可见性，带有警告级别
✅ 生命周期钩子 - 扩展的日志记录、指标和缓存处理系统

⚡ 性能优化

✅ 查询批处理 - 将速率限制槽消耗减少67%
✅ 优化操作 - 协调多查询执行
✅ 高效批处理 - 部分失败处理

🏗️ 清晰架构

✅ 模块化认证 - 分离OAuth和API密钥实现
✅ 领域特定错误 - 10种错误类型，带结构化日志
✅ 类型安全 - 完整的TypeScript覆盖，运行时验证
✅ 零模拟 - 所有测试均使用真实实现（98.5%通过率）

🐛 错误修复

✅ 修复批量更新操作
✅ 修复类型定义错误
✅ 支持问题里程碑分配

📦 安装

快速开始

# 克隆仓库
git clone https://github.com/locomotive-agency/linear-mcp.git
cd linear-mcp

# 安装依赖
npm install

# 构建服务器
npm run build

npm安装（替代方法）

# 全局安装
npm install -g @locomotive/linear-mcp

# 或在项目中本地安装
npm install @locomotive/linear-mcp

🔑 认证设置

获取您的Linear API密钥

前往Linear设置
导航到**“API” → “个人API密钥”**
点击**“创建密钥”**
给它一个标签（例如，“MCP服务器”）
立即复制该密钥（您不会再次看到它）

密钥看起来像：lin_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

🔧 客户端集成

Claude Code

1. 查找您的Claude Code配置文件：

Linux: ~/.claude.json
macOS: ~/.claude.json
Windows: %USERPROFILE%\.claude.json

2. 添加MCP服务器配置：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

3. 重启Claude Code

4. 验证是否正常工作：

询问Claude: "列出我的Linear团队"

Claude Desktop

1. 查找您的Claude Desktop配置：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. 添加MCP服务器配置：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        1. "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

3. 重启Claude Desktop

4. 验证：

打开Claude Desktop
查看MCP服务器指示器
询问："有哪些Linear工具？"

Cursor

1. 打开Cursor设置：

macOS: Cursor → 设置 → MCP
Windows/Linux: 文件 → 首选项 → MCP

2. 添加服务器配置：

编辑或创建~/.cursor/mcp.json（macOS/Linux）或%APPDATA%\.cursor\mcp.json（Windows）：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

3. 重启Cursor

4. 在Cursor聊天中验证：

询问Cursor: "使用MCP工具列出我的Linear团队"

Cline (VS Code扩展)

1. 查找Cline MCP设置：

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. 添加服务器配置：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

3. 刷新VS Code窗口

4. 验证：

打开Cline
检查MCP服务器列表
尝试："列出我的Linear团队"

OpenAI自定义GPTs / ChatGPT

注意：OpenAI不直接支持MCP服务器，但您可以：

选项1：作为本地API使用

将MCP服务器作为HTTP端点运行（需要包装器）
使用自定义GPT动作调用您的端点

选项2：使用Claude Code作为代理

在Claude Code中配置Linear MCP
使用Claude Code与Linear交互
将结果复制到ChatGPT对话中

选项3：直接集成（需要开发）创建围绕此MCP服务器的OpenAI插件/动作包装器。

Continue.dev

1. 查找Continue配置：

所有平台：~/.continue/config.json

2. 将MCP服务器添加到工具部分：

{
  "tools": [
    {
      "type": "mcp",
      "name": "linear",
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  ]
}

3. 重启Continue

Windsurf

1. 创建或编辑Windsurf MCP配置：

位置：~/.windsurf/mcp.json

2. 添加配置：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

3. 重启Windsurf

通用MCP客户端设置

对于任何兼容MCP的客户端：

配置模板：

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["/绝对路径/to/linear-mcp/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "lin_api_your_key_here"
      }
    }
  }
}

要求：

安装Node.js 18+
构建Linear MCP（npm run build）
有效的Linear API密钥
到build/index.js的绝对路径

🚀 功能

问题管理

✅ 创建问题（单个及批量）
✅ 更新问题（单个及批量）
✅ 删除问题（单个及批量）
✅ 使用高级过滤搜索问题
✅ 将问题分配给里程碑
✅ 关联/取消关联相关问题
✅ 在问题上评论（带线程）

项目管理

✅ 使用问题创建项目
✅ 获取带有富文本描述的项目详情
✅ 搜索项目
✅ 创建/更新/删除里程碑
✅ 将问题分配给里程碑
✅ 跟踪项目进度

团队管理

✅ 列出所有团队
✅ 获取团队状态和工作流程
✅ 获取团队标签

用户管理

✅ 获取认证用户信息
✅ 列出用户团队

高级功能

✅ 查询批处理 - 高效执行多个查询
✅ 速率限制保护 - 永不超出API限制
✅ 自动重试 - 从瞬时失败中恢复
✅ 实时监控 - 跟踪API配额使用情况
✅ 生命周期钩子 - 扩展处理系统

📖 使用示例

创建一个问题

// 使用Claude Code、Claude Desktop或Cursor
"在LOCOMOTIVE团队中创建一个新的Linear问题：
标题：实现用户身份验证
描述：添加Google和GitHub提供商的OAuth 2.0身份验证
优先级：高（2）
估算：5个故事点"

批量操作

"搜索LOCOMOTIVE团队中的所有‘进行中’问题，并将其更新为‘审核中’"

项目管理

"创建名为'2025年第四季度功能'的新项目，其中包含这些里程碑：
- Alpha发布（11月1日）
- Beta发布（11月15日）
- 生产（12月1日）

然后为该项目创建5个初始问题。"

查询批处理

// MCP服务器会自动优化相关查询
"获取项目ABC-123的项目详情、所有里程碑和所有问题"
// 这内部使用了查询批处理 - 仅使用1个速率限制槽而不是3个

🧪 测试覆盖率

统计数据

总测试数：206
通过：203（98.5%）
跳过：3
测试套件：10/10通过

测试类别

所有功能的单元测试
与真实Linear API的集成测试
弹性测试（速率限制、重试）
架构测试（钩子、认证、错误）
生产代码中无模拟

运行测试

# 运行所有测试
npm test

# 运行特定测试套件
npm test -- rate-limiter.test.ts

# 在监视模式下运行测试
npm test:watch

# 运行集成测试（需要LINEAR_API_KEY）
npm run test:integration

🏗️ 架构

模块化设计

src/
├── auth/               # 模块化认证
│   ├── types.ts       # 认证接口
│   ├── api-key-auth.ts   # API密钥实现
│   ├── oauth-auth.ts     # OAuth实现
│   └── index.ts       # 工厂/适配器
├── core/
│   ├── handlers/      # 带生命周期钩子的领域处理器
│   ├── middleware/    # 速率限制、重试逻辑
│   ├── errors/        # 领域特定错误类型
│   └── types/         # TypeScript定义
├── features/
│   ├── issues/        # 问题管理
│   ├── projects/      # 项目管理
│   ├── teams/         # 团队管理
│   ├── milestones/    # 里程碑管理
│   ├── comments/      # 评论管理
│   └── monitoring/    # 速率限制监控
└── graphql/
    ├── client.ts      # 带批处理的GraphQL客户端
    ├── queries.ts     # 查询定义
    └── mutations.ts   # 变异定义

设计原则

单一职责：每个模块只做一件事
依赖注入：可测试且灵活
基于接口：模块之间的干净契约
类型安全：完整的TypeScript覆盖
无模拟：生产代码中使用真实实现

🛡️ 弹性特性

速率限制

滑动窗口跟踪（每小时、每分钟）
90%的安全阈值，自动排队
尊重Linear API限制（每小时1000次，每分钟100次）
支持Retry-After头

重试逻辑

5次尝试，指数退避
智能错误检测（可重试与不可重试）
防止雷同效应的抖动
可配置延迟：100ms → 200ms → 400ms → 800ms → 1600ms

监控

实时配额可见性
警告级别：正常（<80%），警告（80-95%），关键（≥95%）
达到阈值时控制台警报
仪表盘准备的JSON响应

工具：linear_get_rate_limit_status

"检查我的Linear API配额状态"

// 返回：
{
  "warningLevel": "正常",
  "usage": {
    "requestsThisHour": 150,
    "hourlyUsagePercent": 15.0
  },
  "quota": {
    "remainingHour": 850,
    "resetTime": "3245秒后"
  }
}

🎯 可用工具（总计27个）

问题管理（11个工具）

`linear_create_issue`

创建单个问题，支持所有字段（标题、描述、团队、指派人、优先级、估算、项目、自定义显示）。

`linear_create_issues`

批量操作 - 一次API调用创建多个问题。比单独创建快约10倍。

`linear_update_issue`

更新任何问题字段：标题、描述、指派人、优先级、状态、项目或里程碑。

`linear_bulk_update_issues`

批量操作 - 以相同更改更新多个问题。每个问题错误处理高效。

`linear_update_issue_milestone`

将问题分配给里程碑或将里程碑分配移除（传递null/空）。

`linear_search_issues`

使用高级过滤搜索问题：查询文本、团队、指派人、状态、优先级。支持分页。提示：保持first参数≤20以获得最佳性能。

`linear_delete_issue`

通过标识符（LOC-123）或UUID删除单个问题。

`linear_delete_issues`

批量操作 - 一次性删除多个问题。

`linear_link_issues`

创建问题之间的关系：“阻止”，“相关”或“重复”。

`linear_unlink_issues`

移除问题之间的关系。

`linear_get_issue_comments`

获取问题的所有评论，包括线程回复。支持分页和已归档评论。

`linear_create_comment`

向问题添加评论或创建线程回复。支持Markdown。OAuth应用可以设置自定义显示名称。

项目管理（3个工具）

`linear_create_project_with_issues`

原子操作 - 创建项目和初始问题在一个事务中。重要：teamIds是一个数组，不是单个teamId。

`linear_get_project`

获取详细的项目信息，带有富文本描述（documentContent支持）。

`linear_search_projects`

按精确名称匹配搜索项目。

里程碑管理（7个工具）

`linear_create_project_milestone`

创建单个里程碑，带有名称、描述、目标日期和排序顺序。

`linear_create_project_milestones`

批量操作 - 一次调用为项目创建多个里程碑。

`linear_get_project_milestone`

获取详细的里程碑信息，包括相关问题。

`linear_get_project_milestones`

列出特定项目的所有里程碑，支持分页。

`linear_search_project_milestones`

使用过滤器搜索里程碑：名称、项目、目标日期。

`linear_update_project_milestone`

更新里程碑属性：名称、描述、目标日期、排序顺序或移动到不同的项目。

`linear_delete_project_milestone`

永久删除里程碑。

团队管理（1个工具）

`linear_get_teams`

列出所有团队，带有状态、标签和工作流程细节。 最佳实践：在会话开始时调用一次并缓存团队ID。

用户管理（1个工具）

`linear_get_user`

获取认证用户信息：ID、姓名、电子邮件、可访问团队。用途：验证认证，获取用于分配的用户ID。

线性-MCP

项目介绍

Linear MCP Server - 生产级

✨ 关键改进

🛡️ 企业级弹性

⚡ 性能优化

🏗️ 清晰架构

🐛 错误修复

📦 安装

快速开始

npm安装（替代方法）

🔑 认证设置

获取您的Linear API密钥

🔧 客户端集成

Claude Code

Claude Desktop

Cursor

Cline (VS Code扩展)

OpenAI自定义GPTs / ChatGPT

Continue.dev

Windsurf

通用MCP客户端设置

🚀 功能

问题管理

项目管理

团队管理

用户管理

高级功能

📖 使用示例

创建一个问题

批量操作

项目管理

查询批处理

🧪 测试覆盖率

统计数据

测试类别

运行测试

🏗️ 架构

模块化设计

设计原则

🛡️ 弹性特性

速率限制

重试逻辑

监控

🎯 可用工具（总计27个）

问题管理（11个工具）

linear_create_issue

linear_create_issues

linear_update_issue

linear_bulk_update_issues

linear_update_issue_milestone

linear_search_issues

linear_delete_issue

linear_delete_issues

linear_link_issues

linear_unlink_issues

linear_get_issue_comments

linear_create_comment

项目管理（3个工具）

linear_create_project_with_issues

linear_get_project

linear_search_projects

里程碑管理（7个工具）

linear_create_project_milestone

linear_create_project_milestones

linear_get_project_milestone

linear_get_project_milestones

linear_search_project_milestones

linear_update_project_milestone

linear_delete_project_milestone

团队管理（1个工具）

linear_get_teams

用户管理（1个工具）

linear_get_user

监控与可观测性（1个工具）

`linear_create_issue`

`linear_create_issues`

`linear_update_issue`

`linear_bulk_update_issues`

`linear_update_issue_milestone`

`linear_search_issues`

`linear_delete_issue`

`linear_delete_issues`

`linear_link_issues`

`linear_unlink_issues`

`linear_get_issue_comments`

`linear_create_comment`

`linear_create_project_with_issues`

`linear_get_project`

`linear_search_projects`

`linear_create_project_milestone`

`linear_create_project_milestones`

`linear_get_project_milestone`

`linear_get_project_milestones`

`linear_search_project_milestones`

`linear_update_project_milestone`

`linear_delete_project_milestone`

`linear_get_teams`

`linear_get_user`