使用说明

线性MCP服务器

A. 模型上下文协议（MCP）使Claude等AI代理能够与之交互的服务器线性问题跟踪。搜索、创建、更新问题等，全部通过自然语言完成。

⚡ 30秒快速启动

git clone https://github.com/yourusername/linear-mcp-server.git
cd linear-mcp-server
npm install
npm run setup:claude YOUR_LINEAR_API_KEY

完成！ 重新启动Claude Desktop并开始使用Linear：

“显示分配给我的所有问题”
“为登录页面创建错误报告”
“我可以加入哪些团队？”

从获取API密钥线性设置

你能做什么？

设置后，您可以要求Claude：

📋 搜索和浏览

“显示分配给我的所有高优先级错误”
“在工程团队中查找与身份验证相关的问题”
“我目前的任务是什么？”

✨ 创建和更新

“在设计团队中创建暗模式的新功能请求”
“将问题ENG-123更新为高优先级并将其分配给我”
“添加注释以发布状态更新的PROJ-456”

🔍 获取信息

“我在Linear有哪些团队？”
“显示工程团队的工作流状态”
“获取问题ENG-789的详细信息”

全部9个可用工具

工具	说明
`search_issues`	使用强大的查询搜索和过滤线性问题
`create_issue`	创建具有优先级、受让人等的新问题
`update_issue`	修改现有问题（标题、描述、受让人、优先权、州）
`get_issue`	检索有关特定问题的详细信息
`get_my_issues`	将所有问题分配给您
`get_teams`	列出工作区中的所有团队
`get_workflow_states`	查看团队的工作流状态
`add_comment`	为问题添加评论（支持Markdown）
`health_check`	验证API连接和身份验证

特性

核心功能

搜索问题：使用团队、状态和受让人筛选器在Linear中搜索问题
创建问题：在Linear中创建新问题，包括标题、描述、受让人和优先级
更新问题：修改现有问题，包括标题、描述、受让人、优先级和工作流状态
按ID获取问题：检索具有完整详细信息的特定问题
列出团队：获取线性工作区中所有团队的列表
获取我的问题：使用增强的筛选检索分配给当前用户的问题
工作流状态：列出团队的所有工作流状态
添加注释：对现有问题添加评论
健康检查：验证API连接和身份验证状态

性能和可靠性

速率限制：内置节流（10 req/sec）以防止API滥用
查看器缓存：5分钟的用户信息缓存可将API调用减少约95%
输入验证：对所有工具输入进行基于Zod的模式验证
错误上下文：带有调试相关参数的详细错误消息
增强的问题数据：问题包括全面的团队和项目信息

代码质量

类型安全：完全类型化的界面，没有 any 类型
JSDoc文件：全面的API文档和示例
测试覆盖率：98.89%的声明覆盖率，170项测试通过
整洁架构：具有单例模式的服务层
日志记录：使用Pino进行高级日志记录（仅限stderr，无stdout污染）
MCP协议合规性：完全遵守模型上下文协议标准

建筑

src/
├── index.ts              # Main MCP server entry point
├── types.ts              # TypeScript interfaces and type definitions
├── utils/
│   ├── config.ts         # Configuration management with validation
│   ├── error.ts          # Error handling utilities and custom error classes
│   ├── logger.ts         # Enhanced logging with Pino integration
│   └── validation.ts     # Zod schemas for input validation
└── services/
    └── linearService.ts  # Linear API service with rate limiting and caching

安装和设置

自动设置（推荐）

开始使用Claude Desktop的最快方法：

# 1. Install dependencies and build
npm install

# 2. Run setup with your Linear API key
npm run setup:claude YOUR_LINEAR_API_KEY

# 3. Restart Claude Desktop - you're done!

安装脚本将：

✅ 如果需要，自动构建项目
✅ 验证您的API关键工作
✅ 为您的操作系统配置Claude Desktop
✅ 使用您的团队展示个性化示例

配置

创建一个 .env 根目录中的文件，包含以下变量：

LINEAR_API_KEY=your_linear_api_key
LOG_LEVEL=info
NODE_ENV=development

环境变量

变量	描述	默认值	必填
LINEAR_API_KEY	您的线性API键	-	✅ 是的
LOGLEVEL	日志记录级别（跟踪、调试、信息、警告、错误）	信息	否
NODE_ENV	环境（开发、生产）	开发	否
PORT	HTTP服务器的端口（如果使用）	3000	否
ENABLE_RATE_LIMIT	启用速率限制	false	否
RATE_LIMIT_MAX	每个窗口的最大请求数	100	否
RATE_LIMIT_WINDOW_MS	速率限制窗口（毫秒）	60000	否

获取线性API密钥

首选线性设置
单击“创建API密钥”
给它一个描述性的名称，并选择合适的范围
将生成的密钥复制到您的 .env 文件

用法

作为MCP服务器运行

主要用例是作为通过stdio连接的MCP服务器：

npm start

发展模式

对于手表模式的开发：

npm run watch

与MCP客户端集成

此服务器旨在与MCP兼容的客户端配合使用。服务器通过stdio传输进行通信，并提供九个主要工具：

search_issues -使用增强的团队/项目信息搜索和过滤线性问题
create_issue -在Linear中创建新问题
update_issue -修改现有问题，包括标题、描述、受让人、优先权和州
get_issue -按ID检索具有完整详细信息的特定问题
get_my_issues -通过全面筛选将问题分配给当前用户
get_teams -列出工作区中的所有团队
get_workflow_states -列出团队的所有工作流状态
add_comment -向问题添加评论
health_check -验证API连接和身份验证

客户端集成

克劳德桌面版

自动设置 建议使用（见上文安装部分）。

手动设置 -如果您更喜欢手动配置：

macOS/Linux

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

视窗

编辑 %APPDATA%/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "linear": {
      "command": "node",
      "args": ["C:\\path\\to\\your\\linear-mcp-server\\build\\index.js"],
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  }
}

VS代码集成

对于支持MCP扩展的VS Code：

安装MCP兼容扩展（例如“MCP客户端”）
将服务器配置添加到VS代码设置中：

{
  "mcp.servers": {
    "linear": {
      "command": "node",
      "args": ["/path/to/your/linear-mcp-server/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  }
}

游标IDE集成

对于支持MCP的Cursor IDE：

打开光标设置（Cmd/Ctrl+，）
搜索“MCP”或“模型上下文协议”
添加服务器配置：

{
  "mcp.servers": {
    "linear": {
      "command": "node",
      "args": ["/path/to/your/linear-mcp-server/build/index.js"],
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  }
}

或者使用光标命令调色板：

按Cmd/Ctrl+Shift+P
键入“MCP:添加服务器”
出现提示时输入服务器详细信息

持续开发集成

对于Continue.dev（VS代码/JetBrains扩展）：

添加到您的 ~/.continue/config.json:

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

其他MCP客户端

对于任何兼容MCP的客户端，请使用以下连接详细信息：

运输标准： stdio
命令: node /path/to/linear-mcp-server/build/index.js
环境：设置 LINEAR_API_KEY 到您的Linear API键

与NPX一起使用（替代）

您还可以使用npx全局安装和运行：

# Install globally
npm install -g linear-mcp-server

# Use with Claude Desktop
{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["linear-mcp-server"],
      "env": {
        "LINEAR_API_KEY": "your_linear_api_key_here"
      }
    }
  }
}

Docker集成

在Docker容器中运行服务器：

# Dockerfile
FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
EXPOSE 3000
CMD ["node", "build/index.js"]

# Build and run
docker build -t linear-mcp-server .
docker run -e LINEAR_API_KEY=your_key linear-mcp-server

验证

设置集成后，验证其是否正常工作：

克劳德桌面版：在可用工具列表中查找线性工具
VS Code：检查MCP扩展状态是否成功连接
命令行：直接测试服务器：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npm start

您应该看到一个列出所有九个可用工具的响应： search_issues, create_issue, update_issue, get_issue, get_my_issues, get_teams, get_workflow_states, add_comment，以及 health_check.

api参考

工具： `search_issues`

使用高级过滤选项在Linear中搜索问题。

输入架构:

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query"
    },
    "teamId": {
      "type": "string", 
      "description": "Team ID to filter by"
    },
    "status": {
      "type": "string",
      "description": "Status to filter by"
    },
    "assigneeId": {
      "type": "string",
      "description": "Assignee ID to filter by. Use 'me' to filter by the current user"
    },
    "limit": {
      "type": "number",
      "description": "Maximum number of issues to return"
    }
  },
  "required": ["query"]
}

响应:

{
  "issues": [
    {
      "id": "issue-id",
      "identifier": "TEAM-123", 
      "title": "Issue title",
      "description": "Issue description",
      "status": "In Progress",
      "url": "https://linear.app/team/issue/TEAM-123",
      "assignee": "John Doe",
      "createdAt": "2023-01-01T00:00:00.000Z",
      "team": {
        "id": "team-id",
        "name": "Team Name",
        "key": "TEAM"
      },
      "project": {
        "id": "project-id",
        "name": "Project Name",
        "url": "https://linear.app/project/project-id",
        "status": "Active"
      }
    }
  ]
}

工具： `create_issue`

使用完全自定义选项在Linear中创建新问题。

输入架构:

{
  "type": "object",
  "properties": {
    "teamId": {
      "type": "string",
      "description": "Team ID"
    },
    "title": {
      "type": "string", 
      "description": "Issue title"
    },
    "description": {
      "type": "string",
      "description": "Issue description"
    },
    "assigneeId": {
      "type": "string",
      "description": "Assignee ID. Use 'me' to assign to the current user"
    },
    "priority": {
      "type": "number",
      "description": "Issue priority (0-4)"
    }
  },
  "required": ["teamId", "title"]
}

响应:

{
  "id": "issue-id",
  "identifier": "TEAM-123",
  "title": "Issue title", 
  "url": "https://linear.app/team/issue/TEAM-123"
}

工具： `update_issue`

使用全面的修改选项更新Linear中的现有问题。

输入架构:

{
  "type": "object",
  "properties": {
    "issueId": {
      "type": "string",
      "description": "Issue ID to update"
    },
    "title": {
      "type": "string",
      "description": "New issue title"
    },
    "description": {
      "type": "string",
      "description": "New issue description"
    },
    "assigneeId": {
      "type": "string",
      "description": "New assignee ID. Use 'me' to assign to current user, empty string to unassign"
    },
    "priority": {
      "type": "number",
      "description": "New issue priority (0-4)"
    },
    "stateId": {
      "type": "string",
      "description": "New workflow state ID"
    }
  },
  "required": ["issueId"]
}

响应:

{
  "id": "issue-id",
  "identifier": "TEAM-123",
  "title": "Updated issue title",
  "url": "https://linear.app/team/issue/TEAM-123",
  "status": "In Progress"
}

工具： `get_my_issues`

通过增强的过滤和信息获取分配给当前用户的问题。

输入架构:

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "number",
      "description": "Maximum number of issues to return (default: 50, max: 250)"
    }
  }
}

响应:

{
  "issues": [
    {
      "id": "issue-id",
      "identifier": "TEAM-123",
      "title": "Issue title",
      "description": "Issue description",
      "status": "In Progress",
      "url": "https://linear.app/team/issue/TEAM-123",
      "assignee": "John Doe",
      "createdAt": "2023-01-01T00:00:00.000Z",
      "team": {
        "id": "team-id",
        "name": "Team Name",
        "key": "TEAM"
      },
      "project": {
        "id": "project-id",
        "name": "Project Name",
        "url": "https://linear.app/project/project-id",
        "status": "Active"
      }
    }
  ]
}

工具： `get_teams`

让所有团队进入工作区。

输入架构:

{
  "type": "object",
  "properties": {}
}

响应:

{
  "teams": [
    {
      "id": "team-id",
      "name": "Team Name",
      "key": "TEAM",
      "description": "Team description"
    }
  ]
}

工具： `get_issue`

按ID获取特定问题的详细信息。

输入架构:

{
  "type": "object",
  "properties": {
    "issueId": {
      "type": "string",
      "description": "The ID of the issue to retrieve"
    }
  },
  "required": ["issueId"]
}

响应:

{
  "id": "issue-id",
  "identifier": "TEAM-123",
  "title": "Issue title",
  "description": "Issue description",
  "status": "In Progress",
  "url": "https://linear.app/team/issue/TEAM-123",
  "assignee": "John Doe",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "team": {
    "id": "team-id",
    "name": "Team Name",
    "key": "TEAM"
  },
  "project": {
    "id": "project-id",
    "name": "Project Name",
    "url": "https://linear.app/project/project-id",
    "status": "Active"
  }
}

工具： `get_workflow_states`

获取特定团队的所有工作流状态。

输入架构:

{
  "type": "object",
  "properties": {
    "teamId": {
      "type": "string",
      "description": "The ID of the team"
    }
  },
  "required": ["teamId"]
}

响应:

{
  "states": [
    {
      "id": "state-id",
      "name": "In Progress",
      "type": "started",
      "description": "Work is in progress",
      "position": 1
    },
    {
      "id": "state-id-2",
      "name": "Done",
      "type": "completed",
      "description": "Work is completed",
      "position": 2
    }
  ]
}

工具： `add_comment`

为现有问题添加注释。

输入架构:

{
  "type": "object",
  "properties": {
    "issueId": {
      "type": "string",
      "description": "The ID of the issue to comment on"
    },
    "body": {
      "type": "string",
      "description": "The comment text (supports markdown)"
    }
  },
  "required": ["issueId", "body"]
}

响应:

{
  "id": "comment-id",
  "body": "This is my comment",
  "createdAt": "2023-01-01T00:00:00.000Z",
  "issueId": "issue-id"
}

工具： `health_check`

检查线性API的运行状况和连接。

输入架构:

{
  "type": "object",
  "properties": {}
}

响应:

{
  "status": "healthy",
  "apiConnected": true,
  "userId": "user-id",
  "userName": "John Doe"
}

或者，如果不健康：

{
  "status": "unhealthy",
  "apiConnected": false,
  "error": "Error message"
}

发展

项目结构

src/index.ts：具有MCP协议处理的主服务器入口点
src/types.ts：所有接口的TypeScript类型定义
src/utils/：用于配置、日志记录和错误处理的实用模块
src/services/：线性API交互的业务逻辑层

关键设计模式

单例模式：用于确保单实例管理的服务
误差边界模式：各级全面的错误处理
配置模式：具有验证功能的集中配置
服务层模式：API逻辑和MCP处理之间的清洁分离

可用脚本

npm run build         # Build TypeScript to JavaScript
npm run watch         # Watch mode for development
npm start             # Start the MCP server
npm test              # Run all tests with coverage
npm run setup:claude  # Auto-configure Claude Desktop
npm run repair:claude # Fix malformed Claude Desktop config

测试

该项目包括全面的测试覆盖范围：

# Run all tests
npm test

# Watch mode for test development
npm test -- --watch

# Run specific test file
npm test -- tests/unit/services/linearService.test.ts

当前测试覆盖范围：

总体而言：98.89%的声明覆盖率
linearService.ts：覆盖率98.24%
170个单元和集成套件通过测试

测试包括：

LinearService方法的单元测试
MCP工具处理程序的集成测试
配置验证测试
错误处理场景

故障排除

常见问题

“缺少LINEAR_API_KEY”：确保您的 .env 文件存在并且包含有效的线性API密钥
“服务器不支持工具”：这表示MCP客户端兼容性问题
“无法获取团队”：检查您的Linear API密钥权限
Claude配置中的JSON语法错误：使用修复脚本修复格式错误的配置文件

MCP通信问题

如果您遇到JSON解析错误或与MCP客户端（Cursor、Claude Desktop等）的通信问题：

症状

JSON中X位置的数组元素后应有“”、“”或“]”
“意外的令牌'X'不是有效的JSON”
客户端反复显示“命令客户端错误”
MCP工具未出现或无法执行

根本原因

这些问题通常在以下情况下发生 日志输出干扰JSON-RPC通信MCP协议要求：

标准输出：仅JSON-RPC消息
标准错误：所有日志输出

解决方案

✅ 服务器端（已在v0.3.1+中修复） 服务器现在将日志记录与JSON-RPC通信正确分离：

# Logs go to stderr, JSON-RPC to stdout
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

✅ 客户端验证

重新启动MCP客户端 （光标、克劳德桌面等）更新后
检查客户端日志 用于成功连接消息
测试基本功能：尝试列出工具或调用一个简单的工具

✅ 手动测试

# Test tools list (should return clean JSON)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node build/index.js

# Test simple tool call
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_teams", "arguments": {}}}' | node build/index.js

✅ 调试模式 要进行故障排除，请启用调试日志记录（输出到stderr）：

LOG_LEVEL=debug
NODE_ENV=development

如果更新到v0.3.1+后问题仍然存在，请检查您是否使用了最新版本：

npm run build  # Rebuild with latest fixes

JSON配置错误

如果您在中看到JSON解析错误，如“意外令牌”或“不是有效的JSON” Claude桌面配置:

快速修复

# Run the repair script to fix JSON syntax issues
npm run repair:claude

# Then try setting up again
npm run setup:claude

手动修复

完全关闭克劳德桌面
导航到配置文件位置：
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- 视窗: %APPDATA%/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
删除配置文件（将自动创建备份）
再次运行安装脚本： npm run setup:claude

调试

通过设置启用调试日志记录 LOG_LEVEL=debug 在你的 .env 文件：

LOG_LEVEL=debug

这将提供所有API调用和服务器操作的详细日志。

演出

服务器通过以下方式进行了性能优化：

速率限制：将API调用限制为每秒10个请求，以防止API滥用
查看器缓存：用于用户信息的5分钟TTL缓存可将API调用减少约95%
并行处理：使用的并发API调用 Promise.all()
单例模式：高效的资源管理
结构化日志记录：最小的性能开销（仅限stderr）
TypeScript：编译时优化
输入验证：基于Zod的快速模式验证

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。

开发设置

克隆该仓库
克隆你的叉子： git clone https://github.com/yourusername/linear-mcp-server.git
安装依赖项： npm install
创建一个 .env 使用您的Linear API密钥文件
进行更改
运行测试： npm test
提交拉取请求

代码的风格

对所有新代码使用TypeScript
遵循现有的代码组织模式
添加适当的错误处理
包括公共API的JSDoc注释
确保所有测试通过

使用说明

线性MCP服务器

⚡ 30秒快速启动

你能做什么？

全部9个可用工具

特性

核心功能

性能和可靠性

代码质量

最近的改进✨

建筑

安装和设置

自动设置（推荐）

配置

环境变量

获取线性API密钥

用法

作为MCP服务器运行

发展模式

与MCP客户端集成

客户端集成

克劳德桌面版

macOS/Linux

视窗

VS代码集成

游标IDE集成

持续开发集成

其他MCP客户端

与NPX一起使用（替代）

Docker集成

验证

api参考

工具： search_issues

工具： create_issue

工具： update_issue

工具： get_my_issues

工具： get_teams

工具： get_issue

工具： get_workflow_states

工具： add_comment

工具： health_check

发展

项目结构

关键设计模式

可用脚本

测试

故障排除

常见问题

MCP通信问题

症状

根本原因

解决方案

JSON配置错误

快速修复

手动修复

调试

演出

许可证

贡献

开发设置

代码的风格

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件

科学研究的开源MCP服务器

工具： `search_issues`

工具： `create_issue`

工具： `update_issue`

工具： `get_my_issues`

工具： `get_teams`

工具： `get_issue`

工具： `get_workflow_states`

工具： `add_comment`

工具： `health_check`