星战科技xingzhan.cloud
返回市场
线性流式MCP服务器

线性流式MCP服务器

作者：iceener25 星标更新：2025-09-04
安装使用来源：spider==github.com

项目介绍

Linear MCP 服务器（HTTP / OAuth / 远程）

警告：您自行负责将此服务器连接到您的MCP客户端。语言模型可能会犯错、误解指令或执行意外操作。请检查工具输出，验证更改（例如，使用list_issues），并优先进行小规模、渐进式的写入。在生产环境中，强制实施最小权限凭证、审计日志和审批工作流。

这是一个用于Linear的可流式传输的HTTP MCP服务器，允许您管理问题、项目、团队、用户、评论和周期——无论是本地还是远程。

以下是官方Linear MCP（顶部）与本MCP（底部）之间的比较。

<img src="docs/comparison-hd.gif" width="800" />

注意事项

此仓库有两种运行方式：

  • 作为本地工作流程的Node/Hono服务器
  • 作为远程交互的Cloudflare Worker

这里的HTTP/OAuth设置是为了方便开发，而不是为了生产级的安全性。如果您正在部署到Cloudflare，请参阅远程模型上下文协议服务器（MCP）以获取详细信息。

动机

我是Linear的忠实粉丝，并且每天都在使用它——无论是个人项目还是专业工作流程，包括自动化。撰写本文时，官方的MCP服务器尚未完全优化以适应语言模型（这可能很快就会改变，因为Linear正在积极改进它）。

此服务器构建时考虑了几个关键目标：

  • 让LLMs能够在一个动作中（如workspace_metadata）轻松找到诸如团队ID、项目ID、状态ID或用户ID等信息，而无需调用多个工具来收集所需数据。
  • 包含清晰的MCP指令和模式描述，减少API术语，使模型更有可能按正确顺序使用正确的工具。
  • 将API响应映射成人类可读的反馈——这对LLM和用户都有帮助。
  • 提供下一步的提示和建议，以及如何利用可用数据或从错误中恢复的技巧。
  • 支持批量操作（例如，add_issues而不是add_issue），以便LLM可以一次性执行多个步骤。
  • 预取相关值——例如，返回一个问题的状态ID和实际状态名称。
  • 隐藏未在给定团队设置中启用的工具（如cycles_list），以减少噪音。
  • 调整模式以匹配工作区偏好，例如问题优先级格式。

简而言之，这不是Linear API的直接镜像——它是定制化的，使得AI代理和聊天客户端确切知道如何有效地使用它。

安装与开发

前提条件：Bun，Node.js 24+，Linear账户。对于远程：一个Cloudflare账户和Wrangler包。

您还需要一个MCP客户端，例如：

运行方式（选择一种）

  1. 本地（API密钥）
  2. 本地 + OAuth
  3. Cloudflare Worker — wrangler dev（本地Worker）
  4. Cloudflare Worker — 远程部署

1) 快速开始（本地工作流程，使用API密钥）

这是最简单的开始方式。使用您的Linear个人访问令牌运行服务器（设置 → 安全）。

https://linear.app/[your-account-name]/settings/account/security

git clone https://github.com/iceener/linear-streamable-mcp-server
cd linear
bun install
cp env.local-api.example .env
# 在.env中更新您的Linear API密钥
bun dev

现在将此服务器连接到Alice（设置 → MCP），并按照以下方式设置：

<img src="docs/alice-local-mcp.png" width="600" />

或者使用Claude Desktop，设置如下：

{
  "mcpServers": {
    "remote-example": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "http://localhost:3040/mcp",
        "--header",
        "Authorization: ${LINEAR_API_KEY}"
      ]
    }
  }
}

2) 替代方案：本地 + OAuth

这是一种更高级的工作流程，因为它需要在Linear中创建一个OAuth应用程序。示例：

<img src="docs/linear-oauth.png" width="600" /> 
git clone https://github.com/iceener/linear-streamable-mcp-server
cd linear
bun install
cp env.local-oauth.example .env

# 更新OAUTH_CLIENT_ID和OAUTH_CLIENT_SECRET
# 添加以下重定向URI：
# alice://oauth/callback
# http://127.0.0.1:3041/linear/callback
# http://localhost:3041/linear/callback
# http://localhost:8788/linear/callback
# https://claude.ai/api/mcp/auth_callback
# https://claude.com/api/mcp/auth_callback
# https://<worker-name>.<account>.workers.dev/linear/callback

bun dev

提示：本地授权服务器（用于OAuth）运行在PORT+1上。如果PORT=3040，则认证在http://localhost:3041上。

当服务器启动后，连接到Alice：

<img src="docs/alice-local-oauth-mcp.png" width="600" />

或者通过Claude Desktop连接：

{
  "mcpServers": {
    "linear": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "http://localhost:3040/mcp",
        "--transport",
        "http-only"
      ],
      "env": { "NO_PROXY": "127.0.0.1,localhost" }
    }
  }
}

RS-仅模式（推荐用于远程客户端）

启用这些标志以要求RS生成的承载令牌。启用后，没有Authorization或带有非映射Bearer <不透明>的请求将收到401和WWW-Authenticate，以便OAuth可以开始（与mcp-remote一起工作）。

# 当缺少Authorization或不是我们的RS令牌之一时挑战
AUTH_REQUIRE_RS=true

# 如果您仍然希望在RS-仅模式下允许Linear PAT作为Bearer，则设置：
AUTH_ALLOW_LINEAR_BEARER=false

3) Cloudflare Worker — wrangler dev（本地Worker）

快速测试本地Worker的方式。

cd linear
bun x wrangler dev --local | cat

如果您想在开发中直接传递PAT：

cd linear
bun x wrangler secret put LINEAR_API_KEY
bun x wrangler dev --local | cat

对于OAuth，还需设置：

cd linear
bun x wrangler secret put OAUTH_CLIENT_ID
bun x wrangler secret put OAUTH_CLIENT_SECRET
# 确保wrangler.toml中的OAUTH_SCOPES和allowlist
bun x wrangler dev --local | cat

端点（开发）：http://127.0.0.1:8787/mcp（Wrangler打印的确切端口）。

4) Cloudflare Worker — 远程部署

Wrangler参考（已包含为linear/wrangler.toml）：

name = "linear-mcp-worker"
main = "src/worker.ts"
compatibility_date = "2025-06-18"
workers_dev = true
compatibility_flags = ["nodejs_compat"]

[vars]
MCP_PROTOCOL_VERSION = "2025-06-18"
AUTH_ENABLED = "true"
AUTH_REQUIRE_RS = "true"
AUTH_ALLOW_LINEAR_BEARER = "false"
OAUTH_AUTHORIZATION_URL = "https://linear.app/oauth/authorize"
OAUTH_TOKEN_URL = "https://api.linear.app/oauth/token"
OAUTH_SCOPES = "read write"
OAUTH_REDIRECT_ALLOW_ALL = "false"       # 开发助手；生产中保持false
OAUTH_REDIRECT_URI = "alice://oauth/callback"
OAUTH_REDIRECT_ALLOWLIST = "alice://oauth/callback,https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback,https://<worker-name>.<account>.workers.dev/linear/callback"
NODE_ENV = "development"                 # 允许开发中回调到localhost

[[kv_namespaces]]
binding = "TOKENS"
id = "REDACTED"

使用API密钥部署：

cd linear
bun x wrangler secret put LINEAR_API_KEY
bun x wrangler deploy

端点：https://<worker-name>.<account>.workers.dev/mcp。

环境示例

  • 本地（API密钥）：env.local-api.example
  • 本地 + OAuth：env.local-oauth.example
  • 通用默认值：env.example

远程（Cloudflare Worker）使用OAuth

  1. 创建KV用于令牌映射，并将其添加到wrangler.toml中：
bun x wrangler kv namespace create TOKENS
  1. 设置秘密和变量：
cd linear
bun x wrangler secret put OAUTH_CLIENT_ID
bun x wrangler secret put OAUTH_CLIENT_SECRET
# 如果您希望直接使用令牌，可以选择设置LINEAR_ACCESS_TOKEN或LINEAR_API_KEY
  1. 确保OAUTH_SCOPES = "read write"并在Linear应用和允许列表中包含您的Worker回调：
https://<worker-name>.<account>.workers.dev/linear/callback
  1. 部署：
bun x wrangler deploy

该Worker会宣传OAuth发现，并使用KV将资源服务器令牌映射到Linear令牌。它复用了本地服务器的相同工具处理器。在RS-仅模式下，它将：

  • 当缺少Authorization时发出401挑战
  • 当呈现非映射Bearer时发出401挑战（除非AUTH_ALLOW_LINEAR_BEARER=true）
  • 在调用工具之前将映射的RS Bearer重写为Linear访问令牌

故障排除（Worker）

  • 如果OAuth无法启动：curl -i -X POST https://<worker>/mcp ...应返回带有WWW-Authenticate和Mcp-Session-Id的401。
  • 如果Claude中的工具显示为空：确保Worker返回tools/list的JSON Schema（此仓库提供），并使用mcp-remote配置Claude（而非Research连接器）。
  • 如果重定向被阻止：设置有效的OAUTH_REDIRECT_URI和允许列表；开发中您可以设置NODE_ENV=development并保留回环主机。

客户端配置

MCP Inspector（快速测试）：

bunx @modelcontextprotocol/inspector
# 连接到：http://localhost:3040/mcp（本地）或您的Worker /mcp URL

Claude Desktop / Cursor通过mcp-remote：

{
  "mcpServers": {
    "linear": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "http://localhost:3040/mcp",
        "--transport",
        "http-only"
      ],
      "env": { "NO_PROXY": "127.0.0.1,localhost" }
    }
  }
}

对于Cloudflare，替换URL为https://<worker-name>.<account>.workers.dev/mcp。

示例

1) 列出今天到期的问题

请求（获取查看者时区/ID以供上下文）：

{
  "name": "workspace_metadata",
  "arguments": { "include": ["profile"] }
}

请求（分配给我，今天到期的问题）：

{
  "name": "list_my_issues",
  "arguments": {
    "filter": { "dueDate": { "eq": "2025-08-15" } },
    "orderBy": "updatedAt",
    "limit": 20
  }
}

响应（示例）：

我的问题：1（限制20）。预览：
- [OVE-142 — 发布发行说明](https://linear.app/example/issue/OVE-142/publish-release-notes) — 状态完成；项目overment；到期日期2025-08-15；负责人Adam

2) 为Alice v3.8创建一个问题并将其添加到项目中

请求（发现团队/项目ID）：

{
  "name": "workspace_metadata",
  "arguments": { "include": ["teams", "projects", "profile"] }
}

创建（省略assigneeId——此工具默认为当前查看者）：

{
  "name": "create_issues",
  "arguments": {
    "items": [
      {
        "title": "发布Alice v3.8应用",
        "teamId": "TEAM_ID",
        "projectId": "ALICE_PROJECT_ID",
        "dueDate": "2025-08-18",
        "priority": 2,
        "description": "部署并发布Alice v3.8到生产环境"
      }
    ]
  }
}

响应（示例）：

创建的问题：1 / 1。OK：item[0]。下一步：使用list_issues（通过ID或number+team.key/team.id，限制=1）验证详细信息。

3) 重新安排一个发布并标记会议已完成

查找发布问题：

{
  "name": "list_issues",
  "arguments": { "q": "Alice发布", "limit": 5 }
}

查找会议问题：

{
  "name": "list_issues",
  "arguments": { "q": "团队会议", "limit": 20 }
}

解决团队的工作流状态（完成）：

{
  "name": "workspace_metadata",
  "arguments": { "include": ["workflow_states"], "teamIds": ["TEAM_ID"] }
}

更新两者：

{
  "name": "update_issues",
  "arguments": {
    "items": [
      { "id": "RELEASE_UUID", "dueDate": "2025-08-16" },
      { "id": "MEETING_UUID", "stateId": "DONE_STATE_ID" }
    ]
  }
}

响应（示例）：

更新的问题：2 / 2。OK：RELEASE_UUID，MEETING_UUID
- [OVE-231 — 发布Alice v3.8应用](https://linear.app/example/issue/OVE-231/release-alice-v38-app)（ID RELEASE_UUID）
  截止日期：2025-08-18 → 2025-08-16
- [OVE-224 — 团队会议](https://linear.app/example/issue/OVE-224/team-meeting)（ID MEETING_UUID）
  状态：当前 → 完成

许可证

MIT