Shortcut MCP

What shortcut-mcp MCP server does

shortcut-mcp MCP server provides an HTTP Model Context Protocol endpoint for Shortcut. It is hosted at https://streamshortcut.staycek.workers.dev/mcp and is implemented as a Cloudflare Worker. The service presents one MCP tool with an action parameter rather than exposing dozens of separate tools.

The available actions cover common story and epic workflows. Agents can find stories, retrieve a story by ID or URL, modify selected story fields, add comments, create new stories, inspect an epic and its stories, send requests to other Shortcut REST API endpoints, or request usage documentation.

How it works

Each request must include the caller's Shortcut API token. The token can be sent in X-Shortcut-Token or as Authorization: Bearer <token>; the custom Shortcut header takes precedence when both are present. The worker is stateless and does not persist the token. There is no OAuth flow, and requests without credentials receive HTTP 401.

The MCP endpoint uses HTTP transport. A health endpoint is available at /health without authentication, while a direct request to Shortcut's member endpoint can verify whether a token is valid. MCP clients should be restarted after their configuration changes so they reload the server definition.

Setup and configuration

Create a token in Shortcut under account API-token settings, then configure the remote MCP URL in the client. For Claude, the documented command is:

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

The same endpoint can be added to Claude Desktop or Claude Code configuration with an HTTP server entry and an X-Shortcut-Token header. Putting the literal token in the configuration avoids problems with environment-variable expansion when a desktop application is launched outside a terminal. A user can also self-host the Worker by cloning the repository, running npm install, and deploying with npm run deploy; the deployed service still expects each user to provide a token.

Tools and capabilities

The shortcut-mcp MCP server exposes these actions through its single tool:

• search: Find stories using a text query or structured filters. With no filter, it returns the user's active stories.
• get: Retrieve story details by story ID or URL.
• update: Change a story's state, estimate, owner, type, name, or description.
• comment: Add a comment to a story.
• create: Create a story with fields such as type, estimate, state, epic, owner, and description.
• epic: Retrieve epic details together with its stories.
• api: Make raw REST API requests for operations not covered by the other actions.
• help: Return documentation for using the tool.

The compact interface is intended to reduce MCP tool-definition context compared with the official Shortcut MCP package described in the README.

Limitations and notes

The shortcut-mcp MCP server requires a valid Shortcut API token for authenticated operations. An expired token, an incorrect token, or a literal unexpanded environment placeholder produces an authentication failure. Cloudflare bot protection can reject some default HTTP clients; the README specifically notes that clients such as Python's urllib may need a normal User-Agent header.

The server does not provide OAuth and does not store credentials. Its built-in actions do not enumerate every Shortcut operation, although the api action provides raw REST access for additional endpoints. Claude must be restarted after an MCP configuration edit. The repository is licensed under MIT.