io.github.stayce/shortcut-mcp

StreamShortcut (Cloudflare Workers)

A lightweight Shortcut MCP deployed on Cloudflare Workers. One tool, eight actions.

Live URL: https://streamshortcut.staycek.workers.dev/mcp

Why?

The official @shortcut/mcp uses ~11,652 tokens for tool definitions (52 tools). StreamShortcut uses ~500 tokens — a ~96% reduction.

Actions

Usage with Claude

You must provide your own Shortcut API token. Get one at: https://app.shortcut.com/settings/account/api-tokens

Option 1: claude mcp add (recommended)

One command, no file editing. Replace YOUR_TOKEN with your real token:

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

Use -s user to make it available in every project instead of just the current one.

Option 2: Edit the config directly

Add this to your Claude Desktop / Claude Code config:

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

Put the literal token in the config. A "${SHORTCUT_API_TOKEN}" reference only resolves if the variable is present in the environment the app was launched from. On macOS, apps started from the Dock or Finder do not read ~/.zshrc, so the variable will be undefined and the server will fail to authenticate. Environment references work reliably only when you launch from a terminal.

Either way, restart Claude afterwards so the new server is picked up.

Authentication

The server is stateless and stores nothing — every request carries your own token, and it is never persisted. Send it either way:

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

X-Shortcut-Token takes precedence if both are present. There is no OAuth flow; an unauthenticated request returns 401 with a WWW-Authenticate header.

Verify It Works

Check the service is up (no token needed):

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

Confirm your token is valid, straight against Shortcut:

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

200 means the token is good; 401 means it's wrong or expired.

Then test the full path — this returns your active stories:

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"}}}'

Once configured in Claude, just ask: "show me my Shortcut stories."

Troubleshooting

Deploy Your Own (Optional)

If you prefer to self-host:

1. Clone and install:

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

2. Deploy:

    npm run deploy

No server-side secrets needed — users always provide their own token.

Development

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

Examples

{"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"}

Related

• streamshortcut - Original stdio version for local use

License

MIT