MCP Linear

MCP Linear

一个用于 Linear GraphQL API 的模型上下文协议（MCP）服务，专为实际项目管理工作流打造，而不只是基本的 issue 增删改查。

功能

MCP Linear 通过实现 MCP 协议，连接 AI 助手与 Linear。借助它，你可以：

• 获取 issue、项目、团队、周期、里程碑、路线图、客户、客户需求，以及工作区／项目／计划／团队／issue／发布／周期文档
• 创建和更新 issue、更改状态、分配负责人并发表评论
• 管理项目、完整且支持差异感知的项目和计划更新生命周期、里程碑、路线图、已保存视图和收藏项
• 创建和管理工作区 Webhook，包括更新和轮换签名密钥
• 准备 OAuth 应用清单和授权 URL、签发具有特定权限范围的客户端凭据令牌，或在以管理型 OAuth 应用身份通过身份验证时管理子 OAuth 应用
• 使用模板、自定义字段和附件
• 使用客户记录、客户状态／层级，以及关联到 issue 或项目的客户需求
• 无需离开 MCP，即可读取通知、订阅、会话、审计记录和集成
• 在执行繁重的规划会话前检查速率限制和服务运行状况

完整清单请参阅 TOOLS.md。

MCP 原生资源和提示词

除了工具，服务还会公开 MCP 资源和提示词，包括：

• 资源：linear://viewer、linear://organization、linear://teams、linear://projects、linear://project/{id}、linear://project/{id}/issues、linear://project/{id}/documents、linear://issue/{id}、linear://document/{id}、linear://roadmap/{id}、linear://milestone/{id}、linear://rate-limit
• 提示词：summarize-project-status、draft-project-update、triage-issue、summarize-document

示例提示词

连接后，你可以使用如下提示词：

• “显示我所有的 Linear issue”
• “在 Frontend 团队中创建一个标题为‘修复登录错误’的新 issue”
• “将 issue FE-123 的状态更改为‘进行中’”
• “将 issue BE-456 分配给 John Smith”
• “按里程碑和周期分组，显示此项目中所有未关闭的 issue”
• “根据当前 Linear 状态起草每周项目更新”
• “查找与某个项目相关的最新文档，并总结关键决策”
• “显示此团队主页上置顶的文档和链接”
• “为 ENG-123 创建文档，并添加资源排序元数据”
• “获取最新项目更新差异，并归档过时的更新”
• “显示此项目的客户需求，并标记重要项”
• “创建计划更新，并隐藏更新正文中生成的差异”
• “为我的 GitHub issue 流水线准备一个启用了客户端凭据的私有 OAuth 应用”
• “为该 GitHub 流水线签发一个权限范围严格受限的客户端凭据令牌”
• “创建一个用于 Issue 和 Comment 事件的 Webhook，然后轮换其签名密钥”

安装

身份验证

个人 API 密钥（默认）

1. 登录你的 Linear 账户：linear.app
2. 点击你的组织头像（左上角）
3. 选择 设置
4. 在左侧边栏中导航到 安全与访问
5. 在 个人 API 密钥下，点击 新建 API 密钥
6. 为密钥命名（例如，MCP Linear Integration）
7. 复制生成的 API 令牌并妥善保存 — 之后将无法再次查看

个人 API 密钥支持常规 Linear 工具和工作区 webhook 工具。它们无法调用 Linear 的 alpha 托管子级 OAuth 应用 API，因为该 API 要求调用方本身是 OAuth 应用。使用个人 API 密钥时，linear_generateOAuthApplicationSetup 仍会准备官方清单和预先填好的 Linear 设置 URL，供管理员确认。

OAuth 访问令牌（托管 OAuth 应用）

要让 MCP 实际创建和管理子级 OAuth 应用，请使用属于有资格管理这些子级应用的 Linear OAuth 应用的访问令牌进行身份验证：

export LINEAR_OAUTH_ACCESS_TOKEN=YOUR_OAUTH_ACCESS_TOKEN
mcp-linear

或者传入 --oauth-token YOUR_OAUTH_ACCESS_TOKEN。显式指定的命令行凭据优先于环境变量；如果同时存在两种环境凭据，则会选择 OAuth 身份验证。请参阅 Linear 的 OAuth 文档和 OAuth 应用清单。

每个 MCP 服务进程使用一个 Linear 凭据。如果管理应用令牌使用 actor=app（无法获得 admin 权限），并且你还需要具有管理员权限的工作区 webhook 工具，请配置两个 MCP 服务条目：一个使用管理 OAuth 令牌执行子级应用操作，另一个使用工作区管理员的个人 API 密钥处理工作区 webhook。具有 admin 权限的用户主体 OAuth 令牌也可以处理 webhook。

OAuth 权限范围是在请求授权 URL 或客户端凭据令牌时选择的；它们不是 OAuth 应用上可修改的字段。MCP 会验证当前 Linear 权限范围、准备授权 URL，并可通过 linear_createOAuthClientCredentialsToken 签发应用主体令牌。对于由 GitHub 托管的流水线，请启用 client_credentials 授权类型，并请求范围尽可能小且满足需求，例如 issues:create。

客户端凭据令牌通常会在 30 天后过期，且没有刷新令牌。Linear 仅允许多个活动令牌使用相同的权限范围集；请求不同的权限范围集会撤销该应用现有的应用主体令牌。因此，令牌工具要求同时设置 confirmSecretExposure: true 和 confirmScopeChangeRisk: true。

创建 OAuth 应用以及轮换 OAuth 或 webhook 密钥时，会通过 MCP 返回一次性密钥材料。这些工具要求设置 confirmSecretExposure: true；请直接将返回的值存入 GitHub Actions 密钥等密钥管理器，不要将其粘贴到源代码管理中或日志里。

Webhook URL 必须是可公开访问的 HTTPS 端点。验证会拒绝 URL 中包含凭据的情况，以及明显指向回环地址、专用网络、链路本地地址或本地主机名的情况。

通过 add-mcp 安装（推荐）

add-mcp 只需一条命令即可将服务安装到 Claude Code、Cursor、Codex、VS Code、Claude Desktop 以及许多其他支持 MCP 的 Agent 中：

npx add-mcp @tacticlaunch/mcp-linear --env LINEAR_API_TOKEN=YOUR_LINEAR_API_TOKEN

添加 -g 可进行全局安装，而不是安装到当前项目中。完整 Agent 列表和标志请参阅 add-mcp 文档。

手动配置

将以下内容添加到 MCP 设置文件中：

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@tacticlaunch/mcp-linear"],
      "env": {
        "LINEAR_API_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

客户端专属配置位置

• Cursor：~/.cursor/mcp.json
• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json
• Claude VSCode Extension：~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• GoMCP：~/.config/gomcp/config.yaml

手动运行

前置条件：

• Node.js（v20+）
• NPM 或 Yarn
• Linear 个人 API 密钥或 OAuth 访问令牌

# Install globally
npm install -g @tacticlaunch/mcp-linear

# Or clone and install locally
git clone https://github.com/tacticlaunch/mcp-linear.git
cd mcp-linear
npm install
npm link  # Makes the package available globally

运行服务

使用 Linear API 令牌运行服务：

mcp-linear --token YOUR_LINEAR_API_TOKEN

或使用管理 OAuth 应用的访问令牌：

mcp-linear --oauth-token YOUR_OAUTH_ACCESS_TOKEN

也可以在环境中设置令牌，然后不带参数运行：

export LINEAR_API_TOKEN=YOUR_LINEAR_API_TOKEN
mcp-linear

验证

默认验证方式如下：

npm test
npm run build

npm test 会运行 Jest 单元测试，并使用官方 MCP SDK 对构建好的 stdio 服务执行冒烟测试，涵盖工具、资源和提示词注册，以及与宿主兼容的架构输出。

开发

本地开发详情请参阅 DEVELOPMENT.md。

链接

tacticlaunch/cursor-memory-bank — 如果你是希望借助 Cursor 改进工作流的开发者，不妨试试看。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。