Shortcut MCP Server
OfficialShortcut MCP Server provides tools to read and manage Shortcut workspace data via MCP.
Users: get current user, current teams, and list users.
Stories: get/search, history, branch name, create/update, upload files, assign/unassign current user, comments, subtasks, tasks, relations, and external links.
Iterations: get/search/create/update/delete, active/upcoming, and get stories.
Epics: get/search/create/update/delete and comments.
Objectives: get/search.
Teams, workflows, projects: list/get and related stories.
Documents: create/update/list/search/get Markdown docs.
Labels: list/get stories/create.
Custom fields: list fields and values.
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 search for stories assigned to me that are in progress"
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
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>"
}
}
}
}
}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
56 toolscustom-fields-listCustom: Fields ListARead-onlyIdempotent
List custom fields and their values (for setting on stories).
Inputs: includeDisabled.
documents-createDocuments: CreateB
Create a new document (Markdown format).
Inputs: title (required), content (required).
documents-get-by-idDocuments: Get By IDARead-onlyIdempotent
Get a document by ID (returns Markdown).
Inputs: docId (required).
documents-listDocuments: ListARead-onlyIdempotent
List all documents.
Inputs: no named parameters.
documents-searchDocuments: SearchCRead-onlyIdempotent
Search for documents.
Inputs: title (required), archived, nextPageToken, createdByCurrentUser, +1 more.
documents-updateDocuments: UpdateC
Update a document's title or content.
Inputs: docId (required), title, content.
epics-createEpics: CreateB
Create a new Shortcut epic.
Inputs: name (required), owner, teamId, description.
epics-create-commentEpics: Create CommentB
Add a comment to an epic.
Inputs: text (required), epicPublicId (required), replyToCommentId.
epics-deleteEpics: DeleteADestructive
Delete an epic (cannot be undone).
Inputs: epicPublicId (required).
epics-get-by-idEpics: Get By IDBRead-onlyIdempotent
Get a Shortcut epic by public ID.
Inputs: epicPublicId (required), full.
epics-searchEpics: SearchCRead-onlyIdempotent
Find Shortcut epics.
Inputs: id, due, name, team, +19 more.
epics-updateEpics: UpdateA
Update an epic. Only provide fields to update.
Inputs: epicPublicId (required), name, state, labels, +10 more.
iterations-createIterations: CreateC
Create a new Shortcut iteration.
Inputs: name (required), endDate (required), startDate (required), teamId, +1 more.
iterations-deleteIterations: DeleteADestructive
Delete an iteration (cannot be undone).
Inputs: iterationPublicId (required).
iterations-get-activeIterations: Get ActiveARead-onlyIdempotent
Get active iterations for current user's teams.
Inputs: teamId.
iterations-get-by-idIterations: Get By IDARead-onlyIdempotent
Get a Shortcut iteration by public ID.
Inputs: iterationPublicId (required), full.
iterations-get-storiesIterations: Get StoriesBRead-onlyIdempotent
Get all stories in an iteration.
Inputs: iterationPublicId (required), includeStoryDescriptions.
iterations-get-upcomingIterations: Get UpcomingARead-onlyIdempotent
Get upcoming iterations for current user's teams.
Inputs: teamId.
iterations-searchIterations: SearchCRead-onlyIdempotent
Find Shortcut iterations.
Inputs: id, name, team, state, +6 more.
iterations-updateIterations: UpdateA
Update an iteration. Only provide fields to update.
Inputs: iterationPublicId (required), name, labels, endDate, +4 more.
labels-createLabels: CreateB
Create a new label.
Inputs: name (required), color, description.
labels-get-storiesLabels: Get StoriesARead-onlyIdempotent
Get all stories with a specific label.
Inputs: labelPublicId (required).
labels-listLabels: ListARead-onlyIdempotent
List all labels in the workspace.
Inputs: includeArchived.
objectives-get-by-idObjectives: Get By IDBRead-onlyIdempotent
Get a Shortcut objective by public ID.
Inputs: objectivePublicId (required), full.
objectives-searchObjectives: SearchCRead-onlyIdempotent
Find Shortcut objectives.
Inputs: id, name, team, owner, +12 more.
projects-get-by-idProjects: Get By IDARead-onlyIdempotent
Get a Shortcut project by ID.
Inputs: projectPublicId (required).
projects-get-storiesProjects: Get StoriesARead-onlyIdempotent
Get all stories in a project.
Inputs: projectPublicId (required).
projects-listProjects: ListARead-onlyIdempotent
List all projects in the workspace.
Inputs: includeArchived.
stories-add-external-linkStories: Add External LinkB
Add an external link to a story.
Inputs: externalLink (required), storyPublicId (required).
stories-add-relationStories: Add RelationC
Add a relationship between stories.
Inputs: storyPublicId (required), relatedStoryPublicId (required), relationshipType.
stories-add-subtaskStories: Add SubtaskB
Add existing story as a sub-task.
Inputs: subTaskPublicId (required), parentStoryPublicId (required).
stories-add-taskStories: Add TaskA
Add a task (checklist item) to a story.
Inputs: storyPublicId (required), taskDescription (required), taskOwnerIds.
stories-assign-current-userStories: Assign Current UserB
Assign current user as story owner.
Inputs: storyPublicId (required).
stories-createStories: CreateA
Create a new Shortcut story. Requires name and either team or workflow.
Inputs: name (required), epic, team, type, +4 more.
stories-create-commentStories: Create CommentC
Add a comment to a story.
Inputs: text (required), storyPublicId (required), replyToCommentId.
stories-create-subtaskStories: Create SubtaskB
Create a new sub-task story.
Inputs: name (required), parentStoryPublicId (required), description.
stories-get-branch-nameStories: Get Branch NameBRead-onlyIdempotent
Get a valid git branch name for a story.
Inputs: storyPublicId (required).
stories-get-by-external-linkStories: Get By External LinkARead-onlyIdempotent
Find stories containing a specific external link.
Inputs: externalLink (required).
stories-get-by-idStories: Get By IDARead-onlyIdempotent
Get a Shortcut story by public ID.
Inputs: storyPublicId (required), full.
stories-get-historyStories: Get HistoryARead-onlyIdempotent
Get the change history for a Shortcut story.
Inputs: storyPublicId (required).
stories-remove-external-linkStories: Remove External LinkADestructive
Remove an external link from a story.
Inputs: externalLink (required), storyPublicId (required).
stories-remove-subtaskStories: Remove SubtaskADestructive
Remove sub-task from parent (becomes regular story).
Inputs: subTaskPublicId (required).
stories-searchStories: SearchCRead-onlyIdempotent
Find Shortcut stories.
Inputs: id, pr, due, epic, +41 more.
stories-set-external-linksStories: Set External LinksA
Replace all external links on a story.
Inputs: externalLinks (required), storyPublicId (required).
stories-unassign-current-userStories: Unassign Current UserB
Remove current user as story owner.
Inputs: storyPublicId (required).
stories-updateStories: UpdateA
Update a Shortcut story. Only provide fields to update.
Inputs: storyPublicId (required), epic, name, type, +13 more.
stories-update-taskStories: Update TaskB
Update a task in a story.
Inputs: taskPublicId (required), storyPublicId (required), isCompleted, taskOwnerIds, +1 more.
stories-upload-fileStories: Upload FileB
Upload a file and attach it to a story.
Inputs: filePath (required), storyPublicId (required).
teams-get-by-idTeams: Get By IDARead-onlyIdempotent
Get a Shortcut team by ID.
Inputs: teamPublicId (required), full.
teams-listTeams: ListARead-onlyIdempotent
List all Shortcut teams.
Inputs: includeArchived.
users-get-currentUsers: Get CurrentARead-onlyIdempotent
Get the current user.
Inputs: no named parameters.
users-get-current-teamsUsers: Get Current TeamsARead-onlyIdempotent
Get a list of teams where the current user is a member.
Inputs: no named parameters.
users-listUsers: ListBRead-onlyIdempotent
Get all users.
Inputs: no named parameters.
workflows-get-by-idWorkflows: Get By IDARead-onlyIdempotent
Get a Shortcut workflow by ID.
Inputs: workflowPublicId (required), full.
workflows-get-defaultWorkflows: Get DefaultARead-onlyIdempotent
Get the default workflow for a team or workspace.
Inputs: teamPublicId.
workflows-listWorkflows: ListARead-onlyIdempotent
List all Shortcut workflows.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 56 tools
Each tool targets a distinct entity or action, with clear differentiation even among many story-related tools. No overlapping purposes.
All tools follow a consistent verb_noun pattern in snake_case (e.g., epics-create, stories-add-relation). No mixing of conventions.
With 56 tools, the server is overly large for its domain, exceeding the typical 15-tool sweet spot and causing potential overhead for agents.
Core CRUD exists for most entities, but notable gaps like missing delete operations for documents and labels hinder full lifecycle coverage.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
The Mercado Pago MCP Server implements the Model Context Protocol to provide AI agents and LLMs with access to Mercado Pago's APIs and tools within compatible development environments. It acts as an intermediary that translates Mercado Pago resources into executable functions (tools) that AI applications can invoke to perform actions and automate flows. The server simplifies integration, enables using documentation to implement or improve code, and optimizes operations through natural language interactions without manual implementations.
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 that integrates Shortcut project management functionality with AI assistants like Cursor, Windsurf, Claude Code, and Zed.33MIT
- FlicenseBqualityDmaintenanceA Model Context Protocol (MCP) server that can be deployed locally via stdio or remotely via SSE/HTTP endpoints, supporting multiple MCP clients including VS Code, Cursor, Windsurf, and Claude Desktop.1-