The Shortcut MCP Server provides comprehensive programmatic access to the Shortcut project management tool via the Model Context Protocol (MCP). With this server, you can:
Story Management: Get, search, create, and update stories; assign/unassign owners; add comments and tasks; manage external links; generate valid branch names; and handle story relationships (blocking, duplicates)
Iteration Management: Get, search, and create iterations; retrieve stories within iterations; list active or upcoming iterations
Epic Management: Get, search, and create epics
Objective Management: Get and search objectives by various criteria
Team & Workflow Management: Get specific teams or workflows; list all teams or workflows
User Information: Get current user details and list all members
@shortcut/mcp
The MCP server for Shortcut.
Usage
Windsurf
See the official Windsurf docs for more information.
Open the
Windsurf MCP Configuration Panel
Click
Add custom server
.Add the following details and save the file:
Cursor
See the official Cursor docs for more information.
Open (or create) the
mcp.json
file (it should be in~/.cursor/mcp.json
or<project-root>/.cursor/mcp.json
, but see Cursor docs for more details).Add the following details and save the file:
Claude Code
See the official Claude Code docs for more information.
You can add a new MCP server from the Claude Code CLI. But modifying the json file directly is simpler!
You can either add a new MCP server from the command line:
Or you can edit the local JSON file directly:
Open the Claude Code configuration file (it should be in
~/.claude.json
).Find the
projects
>mcpServers
section and add the following details and save the file:
Zed
Open your
settings.json
file. Instructions hereAdd the following details and save the file:
Available Tools
Stories
stories-get-by-id - Get a single Shortcut story by ID
stories-search - Find Shortcut stories with filtering and search options
stories-get-branch-name - Get the recommended branch name (based on workspace settings) for a specific story.
stories-create - Create a new Shortcut story
stories-update - Update an existing Shortcut story
stories-upload-file - Upload a file and link it to a story
stories-assign-current-user - Assign the current user as the owner of a story
stories-unassign-current-user - Unassign the current user as the owner of a story
stories-create-comment - Create a comment on a story
stories-add-task - Add a task to a story
stories-update-task - Update a task in a story
stories-add-relation - Add a story relationship (relates to, blocks, duplicates, etc.)
stories-add-external-link - Add an external link to a Shortcut story
stories-remove-external-link - Remove an external link from a Shortcut story
stories-set-external-links - Replace all external links on a story with a new set of links
stories-get-by-external-link - Find all stories that contain a specific external link
Epics
epics-get-by-id - Get a Shortcut epic by ID
epics-search - Find Shortcut epics with filtering and search options
epics-create - Create a new Shortcut epic
Iterations
iterations-get-stories - Get stories in a specific iteration by iteration ID
iterations-get-by-id - Get a Shortcut iteration by ID
iterations-search - Find Shortcut iterations with filtering and search options
iterations-create - Create a new Shortcut iteration with start/end dates
iterations-get-active - Get active iterations for the current user based on team memberships
iterations-get-upcoming - Get upcoming iterations for the current user based on team memberships
Objectives
objectives-get-by-id - Get a Shortcut objective by ID
objectives-search - Find Shortcut objectives with filtering and search options
Teams
teams-get-by-id - Get a Shortcut team by ID
teams-list - List all Shortcut teams
Workflows
workflows-get-default - Get the default workflow for a specific team or the workspace default
workflows-get-by-id - Get a Shortcut workflow by ID
workflows-list - List all Shortcut workflows
Users
users-get-current - Get the current user information
users-get-current-teams - Get a list of teams where the current user is a member
users-list - Get all workspace users
Documents
documents-create - Create a new document in Shortcut with HTML content
Limit tools
You can limit the tools available to the LLM by setting the SHORTCUT_TOOLS
environment variable to a comma-separated list.
Tools can be limited by entity type by just adding the entity, eg
stories
orepics
.Individual tools can also be limitied by their full name, eg
stories-get-by-id
orepics-search
.
By default, all tools are enabled.
Example:
The following values are accepted in addition to the full tool names listed above under Available Tools:
users
stories
epics
iterations
objectives
teams
workflows
documents
Read-only mode
You can run the MCP server in read-only mode by setting the SHORTCUT_READONLY
environment variable to true
. This will disable all tools that modify data in Shortcut.
Example:
Issues and Troubleshooting
Before doing anything else, please make sure you are running the latest version!
If you run into problems using this MCP server, you have a couple of options:
You can also check the list of common issues below to see if there is a known solution already.
Common Issues and Solutions
NPX command not working when using MISE for version management
If you are using MISE for managing Node and NPM versions, you may encounter a "Client closed" error when trying to run the MCP server. Installing this extension into your IDE might help: https://github.com/hverlin/mise-vscode/.
Development
Installation
Build
Running the Development Server Locally
To test your local development version of the MCP server rather than using the published package, follow these steps:
Build the project:
npm run buildCreate or modify your
mcp.json
file to reference your local build:{ "mcpServers": { "shortcut": { "command": "node", "args": [ "/path/to/your/local/mcp-server-shortcut/dist/index.js" ], "env": { "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>" } } } }Place this
mcp.json
file in one of the following locations:For Cursor: In your home directory (
~/.cursor/mcp.json
) or in your project directory (.cursor/mcp.json
)For Windsurf: Use the MCP Configuration Panel to add the custom server
Restart your AI assistant (Cursor or Windsurf) to load the new configuration.
This allows you to instantly test changes to the MCP server without having to publish a new version.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A Model Context Protocol (MCP) server that integrates Shortcut project management with AI tools like Cursor, Windsurf, and Claude Code, allowing direct access to Shortcut data via API token.
Related Resources
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server that enables interaction with Shortcut (formerly Clubhouse) project management tool, allowing users to view and search projects, stories, epics, and objectives, as well as create new items through natural language.Last updated -5
- AsecurityAlicenseAqualityA foundation for building custom local Model Context Protocol (MCP) servers that provide tools accessible to AI assistants like Cursor or Claude Desktop.Last updated -130MIT License
- AsecurityFlicenseAqualityAn all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.Last updated -3
- -securityFlicense-qualityAn MCP (Model Context Protocol) server for efficiently managing Markdown documents in Cursor AI IDE, supporting CRUD operations, search, and metadata management.Last updated -