A Model Context Protocol (MCP) server that provides full access to the Shortcut REST API v3. Manage stories, epics, iterations, workflows, and more directly from any MCP-compatible client.
Shortcut MCP Server
A Model Context Protocol (MCP) server that provides full access to the Shortcut REST API v3. Manage stories, epics, iterations, workflows, and more directly from any MCP-compatible client.
Prerequisites
Setup
1. Install dependencies and build
npm install
npm run build
2. Generate a Shortcut API token
Go to Shortcut > Settings > API Tokens and generate a new token. Copy it for the next step.
3. Configure your MCP client
Add the server to your MCP client configuration. The exact file depends on your client:
| Client | Config file |
|---|---|
| Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) |
| Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) |
| VS Code (Copilot) | .vscode/mcp.json (project) |
Add the following entry (adjust the path to dist/index.js to match your setup):
{
"mcpServers": {
"shortcut": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/shortcut-mcp/dist/index.js"],
"env": {
"SHORTCUT_API_TOKEN": "your-shortcut-api-token"
}
}
}
}
4. Restart your MCP client
Restart or reload your editor/client to pick up the new server configuration.
Available Tools
This server exposes 34 tools organized by resource type.
Stories
| Tool | Description |
|---|---|
| create-story | Create a new story with name, type, description, estimate, labels, owners, and more |
| get-story | Get full details of a story by its ID |
| update-story | Update any story property (name, state, epic, iteration, estimate, labels, etc.) |
| delete-story | Permanently delete a story |
| search-stories | Search stories using Shortcut query syntax |
| list-stories | List stories filtered by project, iteration, or epic |
| bulk-update-stories | Batch-update multiple stories at once (state, epic, iteration, labels, owners, etc.) |
| get-story-history | Get the full change history of a story |
Story Comments
| Tool | Description |
|---|---|
| list-story-comments | List all comments on a story |
| create-story-comment | Add a comment to a story (Markdown supported) |
| update-story-comment | Edit an existing comment |
Story Tasks
| Tool | Description |
|---|---|
| list-story-tasks | List all checklist items on a story |
| create-story-task | Add a checklist item to a story |
| update-story-task | Update a task (mark complete/incomplete, change description, reassign) |
Story Links
| Tool | Description |
|---|---|
| create-story-link | Create a relationship between two stories (blocks, duplicates, or relates to) |
| delete-story-link | Remove a story relationship |
Epics
| Tool | Description |
|---|---|
| create-epic | Create a new epic |
| get-epic | Get full details of an epic including stats |
| update-epic | Update epic properties (name, state, deadline, owners, labels, objectives, etc.) |
| list-epics | List all epics in the workspace |
| list-epic-stories | List all stories belonging to a specific epic |
Iterations
| Tool | Description |
|---|---|
| create-iteration | Create a new iteration (sprint) with start/end dates |
| get-iteration | Get iteration details including cycle time and lead time stats |
| update-iteration | Update iteration properties |
| list-iterations | List all iterations in the workspace |
Workflows
| Tool | Description |
|---|---|
| list-workflows | List all workflows and their states (use this to discover workflow_state_id values) |
| get-workflow | Get a specific workflow and its states |
Labels
| Tool | Description |
|---|---|
| list-labels | List all labels in the workspace |
| create-label | Create a new label with optional color |
Members
| Tool | Description |
|---|---|
| get-current-member | Get info about the authenticated user (your UUID, workspace, role) |
| list-members | List all workspace members (active and disabled) |
Teams / Groups
| Tool | Description |
|---|---|
| list-groups | List all teams (groups) in the workspace |
Objectives
| Tool | Description |
|---|---|
| list-objectives | List all objectives |
| create-objective | Create a new objective |
Search
| Tool | Description |
|---|---|
| search | Search across stories, epics, and iterations using Shortcut search operators |
Custom Fields
| Tool | Description |
|---|---|
| list-custom-fields | List all custom fields and their possible values |
Projects (Legacy)
| Tool | Description |
|---|---|
| list-projects | List all projects (being sunsetted in favor of Teams/Groups) |
Usage Examples
Once connected, you can interact with the server through natural language in your MCP client. Here are some examples:
Creating a story:
"Create a bug story called 'Fix login redirect' and assign it to the current sprint."
Searching stories:
"Find all unestimated feature stories that are in progress."
Sprint planning:
"List all stories in the current iteration and show me which ones are blocked."
Bulk operations:
"Move all stories labeled 'backend' in epic #123 to the 'In Progress' state."
Exploring workflows:
"Show me all available workflow states so I can move a story."
Search Query Syntax
The search-stories and search tools support Shortcut search operators:
| Operator | Example |
|---|---|
| type: | type:feature, type:bug, type:chore |
| state: | state:"In Progress", state:Done |
| label: | label:backend |
| owner: | owner:john |
| epic: | epic:"Q1 Goals" |
| is: | is:started, is:unestimated, is:blocked |
| Free text | login redirect bug |
Operators can be combined: type:feature state:"In Progress" label:backend
Development
npm run dev # Watch mode — recompiles on file changes
npm run build # One-time production build
npm start # Run the compiled server
Rate Limiting
The server includes a built-in rate limiter (200 requests per minute) that automatically queues and throttles requests to stay within Shortcut's API limits.