Shortcut MCP Server
Provides integration with Shortcut's project management platform, allowing AI assistants to interact with Shortcut data using an API token for authentication.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Shortcut MCP Server show me my open stories in the sprint"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
@shortcut/mcp
The MCP server for Shortcut.
Usage
Windsurf
See the official Windsurf docs for more information.
Open the
Windsurf MCP Configuration PanelClick
Add custom server.Add the following details and save the file:
{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}Cursor
See the official Cursor docs for more information.
Open (or create) the
mcp.jsonfile (it should be in~/.cursor/mcp.jsonor<project-root>/.cursor/mcp.json, but see Cursor docs for more details).Add the following details and save the file:
{
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}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!
Open the Claude Code configuration file (it should be in
~/.claude.json).Find the
projects>mcpServerssection and add the following details and save the file:
{
"projects": {
"mcpServers": {
"shortcut": {
"command": "npx",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}
}Zed
Open your
settings.jsonfile. Instructions hereAdd the following details and save the file:
"context_servers": {
"shortcut": {
"settings":{},
"command": {
"path": "<PATH/TO/NPX>",
"args": [
"-y",
"@shortcut/mcp@latest"
],
"env": {
"SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
}
}
}
}Related MCP server: Shortcut.com MCP Server
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
npm installBuild
npm run buildRunning 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.jsonfile 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.jsonfile 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.
Available Tools
33 toolsadd-external-link-to-storyC
Add an external link to a Shortcut story
Inputs: storyPublicId (required), externalLink (required).
add-relation-to-storyC
Add a story relationship to a story
Inputs: storyPublicId (required), relatedStoryPublicId (required), relationshipType.
add-task-to-storyC
Add a task to a story
Inputs: storyPublicId (required), taskDescription (required), taskOwnerIds.
assign-current-user-as-ownerC
Assign the current user as the owner of a story
Inputs: storyPublicId (required).
create-documentA
Create a new document in Shortcut with a title and content. Returns the document's id, title, and app_url. Note: Use HTML markup for the content (e.g., , , , ) rather than Markdown.
Inputs: title (required), content (required).
create-epicC
Create a new Shortcut epic.
Inputs: name (required), owner, description, teamId.
create-iterationC
Create a new Shortcut iteration
Inputs: name (required), startDate (required), endDate (required), teamId, +1 more.
create-storyA
Create a new Shortcut story. Name is required, and either a Team or Workflow must be specified:
If only Team is specified, we will use the default workflow for that team.
If Workflow is specified, it will be used regardless of Team. The story will be added to the default state for the workflow.
Inputs: name (required), description, type, owner, +4 more.
create-story-commentC
Create a comment on a story
Inputs: storyPublicId (required), text (required).
get-active-iterationsB
Get the active Shortcut iterations for the current user based on their team memberships
Inputs: teamId.
get-current-userB
Get the current user
Inputs: no named parameters.
get-epicB
Get a Shortcut epic by public ID
Inputs: epicPublicId (required).
get-iterationB
Get a Shortcut iteration by public ID
Inputs: iterationPublicId (required).
get-iteration-storiesC
Get stories in a specific iteration by iteration public ID
Inputs: iterationPublicId (required), includeStoryDescriptions.
get-objectiveC
Get a Shortcut objective by public ID
Inputs: objectivePublicId (required).
get-stories-by-external-linkC
Find all stories that contain a specific external link
Inputs: externalLink (required).
get-storyC
Get a Shortcut story by public ID
Inputs: storyPublicId (required).
get-story-branch-nameC
Get a valid branch name for a specific story.
Inputs: storyPublicId (required).
get-teamB
Get a Shortcut team by public ID
Inputs: teamPublicId (required).
get-upcoming-iterationsB
Get the upcoming Shortcut iterations for the current user based on their team memberships
Inputs: teamId.
get-workflowC
Get a Shortcut workflow by public ID
Inputs: workflowPublicId (required).
list-membersC
Get all members
Inputs: no named parameters.
list-teamsB
List all Shortcut teams
Inputs: no named parameters.
list-workflowsB
List all Shortcut workflows
Inputs: no named parameters.
remove-external-link-from-storyC
Remove an external link from a Shortcut story
Inputs: storyPublicId (required), externalLink (required).
search-epicsC
Find Shortcut epics.
Inputs: id, name, description, state, +18 more.
search-iterationsC
Find Shortcut iterations.
Inputs: id, name, description, state, +5 more.
search-objectivesC
Find Shortcut objectives.
Inputs: id, name, description, state, +11 more.
search-storiesC
Find Shortcut stories.
Inputs: id, name, description, comment, +40 more.
set-story-external-linksC
Replace all external links on a story with a new set of links
Inputs: storyPublicId (required), externalLinks (required).
unassign-current-user-as-ownerC
Unassign the current user as the owner of a story
Inputs: storyPublicId (required).
update-storyC
Update an existing Shortcut story. Only provide fields you want to update. The story public ID will always be included in updates.
Inputs: storyPublicId (required), name, description, type, +6 more.
update-taskC
Update a task in a story
Inputs: storyPublicId (required), taskPublicId (required), taskDescription, taskOwnerIds, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Each tool has a clearly distinct purpose targeting specific resources and actions in Shortcut, such as stories, epics, iterations, and users. There is no significant overlap; for example, 'create-story' and 'update-story' are distinct, and 'add-external-link-to-story' and 'set-story-external-links' serve different functions (add vs. replace).
Tool names follow a consistent verb-object pattern with hyphens (e.g., 'create-story', 'get-iteration'), making them readable and predictable. Minor deviations exist, such as 'assign-current-user-as-owner' being more verbose, but overall, the naming is highly consistent across the set.
With 33 tools, the count is borderline high for a project management server, potentially overwhelming for agents. While it covers many operations, it might be slightly heavy compared to typical well-scoped servers (3-15 tools), though not extreme.
The tool set provides comprehensive CRUD and lifecycle coverage for Shortcut's domain, including stories, epics, iterations, documents, and users. It supports creation, retrieval, updating, deletion (via removal tools), and search operations, with no obvious gaps for core workflows.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Share one project context across ChatGPT, Claude, Telegram and any MCP client.
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceA 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.5-
- FlicenseNot gradedqualityDmaintenanceAn implementation of a Model Context Protocol server that allows Claude and other AI assistants to interact with Shortcut.com's ticket management system for searching, viewing, creating, and updating stories.-
- AlicenseBqualityDmaintenanceA Model Context Protocol server providing AI assistants with comprehensive project, task, and subtask management capabilities with project-specific storage.2944 npm88MIT
- AlicenseBqualityDmaintenanceA Model Context Protocol server that enables seamless integration between Claude AI and development tools like VSCode, Augment, Vercel, Airtable, and Square.7MIT