# shortcut-mcp [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/stayce/streamshortcut-cloudflare  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/shortcut-mcp

## Description
Shortcut project management. Create, update, search stories and manage workflows.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "shortcut-mcp": {
    "url": "https://streamshortcut.staycek.workers.dev/mcp"
  }
}
```

## Documentation & README

# 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

| Action | Purpose |
|--------|---------|
| `search` | Find stories (default: your active stories); text query or structured filters |
| `get` | Story details by ID or URL |
| `update` | Change state, estimate, owner, type, name, or description |
| `comment` | Add comment to story |
| `create` | Create story with type, estimate, state, epic, owner, description |
| `epic` | Epic details with its stories |
| `api` | Raw REST API access for everything else |
| `help` | Documentation |

## 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:

```bash
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:

```json
{
  "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):

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

Confirm your token is valid, straight against Shortcut:

```bash
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:

```bash
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

| Symptom | Cause |
|---------|-------|
| `401 Missing Shortcut API token` | No token sent — use either `X-Shortcut-Token` or `Authorization: Bearer` |
| `Error: API error (401): Unauthorized` | Token reached the server but Shortcut rejected it — expired or wrong token, or an unexpanded `${SHORTCUT_API_TOKEN}` placeholder sent literally |
| `403 Forbidden` from the worker | Cloudflare bot protection. Some default HTTP clients (e.g. Python's `urllib`) are blocked by user agent — set a normal `User-Agent` header |
| Server missing after config edit | Claude needs a restart; it only reads MCP config at startup |

## Deploy Your Own (Optional)

If you prefer to self-host:

1. Clone and install:
   ```bash
   git clone https://github.com/stayce/streamshortcut-cloudflare
   cd streamshortcut-cloudflare
   npm install
   ```

2. Deploy:
   ```bash
   npm run deploy
   ```

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

## Development

```bash
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

```json
{"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](https://github.com/stayce/streamshortcut) - Original stdio version for local use

## License

MIT