shortcut-mcp

StreamShortcut（Cloudflare Workers）

部署在 Cloudflare Workers 上的轻量级 Shortcut MCP。一个工具，八种操作。

在线 URL： https://streamshortcut.staycek.workers.dev/mcp

为什么？

官方的 @shortcut/mcp 的工具定义约占用 11,652 个 token（52 个工具）。 StreamShortcut 约占用 500 个 token——减少约 96%。

操作

操作	用途
search	查找故事（默认：你的进行中故事）；支持文本查询或结构化筛选条件
get	按 ID 或 URL 获取故事详情
update	更改状态、预估、负责人、类型、名称或描述
comment	为故事添加评论
create	创建故事，可设置类型、预估、状态、Epic、负责人和描述
epic	获取 Epic 详情及其故事
api	访问其他所有功能的原始 REST API
help	文档

与 Claude 搭配使用

你必须提供自己的 Shortcut API 令牌。 获取地址：https://app.shortcut.com/settings/account/api-tokens

选项 1：claude mcp add（推荐）

只需一条命令，无需编辑文件。将 YOUR_TOKEN 替换为你的真实令牌：

claude mcp add --transport http shortcut https://streamshortcut.staycek.workers.dev/mcp --header "X-Shortcut-Token: YOUR_TOKEN"

使用 -s user 可让它在所有项目中可用，而不只是当前项目。

选项 2：直接编辑配置

将以下内容添加到 Claude Desktop / Claude Code 配置中：

{
  "mcpServers": {
    "shortcut": {
      "type": "http",
      "url": "https://streamshortcut.staycek.workers.dev/mcp",
      "headers": {
        "X-Shortcut-Token": "your-token-here"
      }
    }
  }
}

在配置中填写实际令牌。 只有当变量存在于应用启动时所处的环境中，"${SHORTCUT_API_TOKEN}" 引用才会被解析。 在 macOS 上，从 Dock 或 Finder 启动的应用不会读取 ~/.zshrc，因此该变量将未定义，服务器也会认证失败。只有从终端启动应用时，环境变量引用才能可靠地生效。

无论使用哪种方式，之后都要重启 Claude，以加载新的服务器。

身份验证

该服务器是无状态的，不存储任何内容——每个请求都会携带你自己的令牌，且令牌绝不会被持久化。可以通过以下任一方式发送：

X-Shortcut-Token: your-token-here
Authorization: Bearer your-token-here

如果两者都存在，则 X-Shortcut-Token 优先。此处没有 OAuth 流程； 未经身份验证的请求会返回 401 和 WWW-Authenticate 标头。

验证是否正常运行

检查服务是否已启动（无需令牌）：

curl -s https://streamshortcut.staycek.workers.dev/health

直接向 Shortcut 验证你的令牌是否有效：

curl -s -o /dev/null -w "%{http_code}\n" https://api.app.shortcut.com/api/v3/member -H "Shortcut-Token: YOUR_TOKEN"

200 表示令牌有效；401 表示令牌错误或已过期。

然后测试完整流程——这会返回你的进行中故事：

curl -s https://streamshortcut.staycek.workers.dev/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "X-Shortcut-Token: YOUR_TOKEN" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"shortcut","arguments":{"action":"search"}}}'

在 Claude 中完成配置后，只需询问：“显示我的 Shortcut 故事。”

故障排除

现象	原因
401 Missing Shortcut API token	未发送令牌——请使用 X-Shortcut-Token 或 Authorization: Bearer
Error: API error (401): Unauthorized	令牌已到达服务器，但被 Shortcut 拒绝——令牌已过期或错误，或者未展开的 ${SHORTCUT_API_TOKEN} 占位符被原样发送
worker 返回 403 Forbidden	Cloudflare 机器人防护。某些默认 HTTP 客户端（例如 Python 的 urllib）会因用户代理而被拦截——请设置常规的 User-Agent 标头
编辑配置后服务器消失	Claude 需要重启；它只会在启动时读取 MCP 配置

部署自己的实例（可选）

如果你更希望自行托管：

1. 克隆并安装：

   git clone https://github.com/stayce/streamshortcut-cloudflare
   cd streamshortcut-cloudflare
   npm install
   

2. 部署：

   npm run deploy
   

无需服务器端密钥——用户始终提供自己的令牌。

开发

npm run dev        # local server on http://localhost:8787
npm run typecheck  # tsc --noEmit
npm run build      # verify the Worker bundles (dry-run deploy)

示例

{"action": "search"}
{"action": "search", "query": {"owner": "me", "state": "In Progress"}}
{"action": "get", "id": "704"}
{"action": "update", "id": "704", "state": "Done"}
{"action": "comment", "id": "704", "body": "Fixed!"}
{"action": "create", "name": "New bug", "type": "bug", "estimate": 3, "state": "Ready", "owner": "me"}
{"action": "epic", "id": "308"}
{"action": "api", "method": "GET", "path": "/workflows"}
{"action": "help"}

相关项目

• streamshortcut - 用于本地使用的原始 stdio 版本

许可证

MIT