Shortcut MCP Server

Official Shortcut MCP server for managing stories, epics, iterations, objectives, teams, workflows, and docs in Shortcut project management.

Collaboration by Shortcut OAuth2 (hosted) or API Key (local) active

Connect (Remote Server) GitHub Docs npm: @shortcut/mcp

Overview

The Shortcut MCP server is the official Model Context Protocol integration maintained by Shortcut (useshortcut). It exposes the Shortcut project management API to AI assistants so they can read and write stories, epics, iterations, objectives, labels, custom fields, teams, projects, workflows, users, and documents through a standardized interface.

Shortcut offers two ways to run the server. The recommended path is the hosted remote server at https://mcp.shortcut.com/mcp, which uses OAuth and requires no local setup or API token. A local stdio variant is published as the npm package @shortcut/mcp and authenticates with a personal SHORTCUT_API_TOKEN. The server supports a read-only mode (SHORTCUT_READONLY=true) and selective tool filtering through the SHORTCUT_TOOLS env var.

Tool coverage is broad, with roughly 65 tools spanning the core Shortcut object model. Notable capabilities include story search, comment/subtask/task management, story relations and external links, iteration lifecycle (active/upcoming retrieval and CRUD), epic CRUD with comments, and full document operations (create, update, search, list, get).

Tools

Tool	Description
`stories.search`	Search stories using Shortcut query syntax.
`stories.get-by-id`	Get a story by its public ID.
`stories.create`	Create a new story.
`stories.update`	Update fields on an existing story.
`stories.create-comment`	Add a comment to a story.
`stories.assign-current-user / unassign-current-user`	Assign or remove the current user as a story owner.
`stories.add-task / update-task / create-subtask / add-subtask / remove-subtask`	Manage tasks and subtasks on a story.
`stories.add-relation`	Create a relation between two stories.
`stories.add-external-link / remove-external-link / set-external-links / get-by-external-link`	Manage external links on stories.
`stories.get-branch-name`	Get the suggested Git branch name for a story.
`stories.upload-file`	Attach a file to a story.
`epics.search / get-by-id / create / update / delete / create-comment`	Full CRUD and commenting on epics.
`iterations.search / get-by-id / get-stories / create / update / delete`	Manage iterations and list their stories.
`iterations.get-active / get-upcoming`	Retrieve currently active or upcoming iterations.
`labels.list / create / get-stories`	List labels, create a new label, or fetch stories for a label.
`custom-fields.list`	List all custom fields configured in the workspace.
`objectives.search / get-by-id`	Search and retrieve objectives.
`teams.list / get-by-id`	List teams or fetch a team by ID.
`projects.list / get-by-id / get-stories`	Manage and inspect projects.
`workflows.list / get-default / get-by-id`	Retrieve workflow states.
`users.get-current / get-current-teams / list`	Identify the current user and list workspace members.
`documents.create / update / list / search / get-by-id`	Create and manage Shortcut documents.

Setup Guide

Option 1: Hosted server (recommended)

Use the Shortcut-hosted remote MCP server with OAuth. No API token required.

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "shortcut": {
      "url": "https://mcp.shortcut.com/mcp"
    }
  }
}

VS Code:

{
  "servers": {
    "shortcut-mcp": {
      "type": "http",
      "url": "https://mcp.shortcut.com/mcp"
    }
  }
}

Claude Desktop: Download the .mcpb package from the GitHub releases and double-click to install.

Option 2: Local stdio server

Useful for Windsurf, Zed, Claude Code, or any stdio-based client.

Generate a Shortcut API token at https://app.shortcut.com/settings/account/api-tokens.
Add the server config (example for Claude Code in ~/.claude.json):

{
  "mcpServers": {
    "shortcut": {
      "command": "npx",
      "args": ["-y", "@shortcut/mcp@latest"],
      "env": {
        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
      }
    }
  }
}

Optional environment variables

SHORTCUT_READONLY=true: disable all write operations.
SHORTCUT_TOOLS: comma-separated allow-list of tool names to expose.

Prerequisites

Active Shortcut workspace with appropriate permissions.
API token (only for local stdio install).
Node.js available on PATH (for npx).

Use Cases

Triage and update stories from chat: search by query, reassign owners, change workflow state, post comments.
Sprint planning: list upcoming iterations, create stories, attach them to an iteration and epic, set labels and owners.
Engineering workflow: fetch the Git branch name for a story and add an external link back to a PR.
Roadmap reporting: pull all stories under an epic or objective and summarize progress for a status update.
Knowledge capture: create or update Shortcut Docs with meeting notes or specs generated by the assistant.

Example Prompts

"Find all my open stories in the current iteration and post a status comment on each."
"Create a new bug story in the Platform team's backlog titled 'Login redirect loop' with the production-incident label."
"Show me every story in epic 12345 that is not yet started, grouped by owner."
"Get the branch name for story sc-4821 and add the GitHub PR https://github.com/acme/app/pull/991 as an external link."
"List active iterations across all teams and tell me which are at risk based on incomplete stories."

Pros

Official server maintained by Shortcut, with a managed remote endpoint at mcp.shortcut.com.
Broad coverage (~65 tools) across stories, epics, iterations, docs, objectives, and workflows.
Built-in safety controls: SHORTCUT_READONLY flag and SHORTCUT_TOOLS allow-list.
Hosted OAuth option means no API token handling for end users.

Limitations

Claude Desktop integration requires installing a downloaded .mcpb package rather than a simple config entry.
Local stdio mode requires generating and storing a personal API token, which inherits that user's permissions.
No documented tooling for milestones/groups beyond what is mapped to objectives and teams.

Alternatives

Linear MCP server (mcp.linear.app) for teams using Linear instead of Shortcut.
Atlassian Jira MCP server for Jira-based project management.
GitHub MCP server when issue tracking lives in GitHub Issues rather than a dedicated PM tool.