Shortcut MCP Server
Provides 73 tools for interacting with Shortcut's project management API, enabling management of stories, epics, iterations, milestones, projects, labels, workflows, members, linked files, and more, with read, write, delete, and archive operations.
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 stories with query 'bug' in project 'API'"
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 Server
MCP server for connecting Claude, Codex, or any MCP client to the Shortcut project management API. Provides 73 tools covering the full Shortcut API v3 surface.
How it works
This project implements the Model Context Protocol (MCP) — an open standard that lets AI assistants call external tools.
┌──────────────────┐ stdio ┌──────────────────┐ HTTPS ┌──────────────────┐
│ MCP Client │◄──────────────────►│ MCP Server │◄────────────────►│ Shortcut API │
│ (Claude Desktop, │ JSON-RPC over │ (this project) │ REST API v3 │ api.app. │
│ Claude Code, │ stdin/stdout │ │ with API token │ shortcut.com │
│ VS Code, etc.) │ │ src/index.ts │ │ │
└──────────────────┘ └──────────────────┘ └──────────────────┘Server (src/index.ts): Registers 73 tools with the MCP SDK. When a client calls a tool, the server validates the input (via Zod schemas), makes the corresponding REST request to the Shortcut API, and returns the result. All write operations are protected by confirmation guards.
Client (src/client.ts): A standalone test client for development. It spawns the server as a child process, connects over stdio, and lets you call any tool from the command line:
# List available tools
npm run client
# Call a specific tool
npm run client -- list_epics
npm run client -- get_story '{"story_id": 123}'
npm run client -- create_story '{"name": "Test", "project_id": 101, "dry_run": true}'In production, you don't use the test client — your MCP-compatible AI assistant (Claude Desktop, Claude Code, VS Code, etc.) acts as the client and calls tools automatically.
Related MCP server: Shortcut MCP Server
Setup
Install dependencies:
npm installSet your API token:
cp .env.example .env
# then edit .env and set SHORTCUT_API_TOKEN to your Shortcut API tokenOr export directly:
export SHORTCUT_API_TOKEN="<your-token>"You can generate a Shortcut API token at Settings → API Tokens in your Shortcut workspace.
Build:
npm run buildRun
npm startIntegration
Claude Desktop
Add the following to your Claude Desktop config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"shortcut": {
"command": "node",
"args": ["/absolute/path/to/shortcut-mcp-server/dist/index.js"],
"env": {
"SHORTCUT_API_TOKEN": "<your-shortcut-token>"
}
}
}
}Restart Claude Desktop after saving.
Claude Code (CLI)
Add to ~/.claude/settings.json:
{
"mcpServers": {
"shortcut": {
"command": "node",
"args": ["/absolute/path/to/shortcut-mcp-server/dist/index.js"],
"env": {
"SHORTCUT_API_TOKEN": "<your-shortcut-token>"
}
}
}
}VS Code (Claude Extension)
Add to your project's .vscode/mcp.json or workspace settings:
{
"mcpServers": {
"shortcut": {
"command": "node",
"args": ["/absolute/path/to/shortcut-mcp-server/dist/index.js"],
"env": {
"SHORTCUT_API_TOKEN": "<your-shortcut-token>"
}
}
}
}Note: In all configs above, replace
/absolute/path/to/shortcut-mcp-serverwith the actual path where you cloned this repo, and<your-shortcut-token>with your Shortcut API token.
Guardrails for write tools
All mutating tools support safety guardrails:
confirm="CONFIRM_WRITE"is required to execute any write/update/create.dry_run=truereturns the exact request payload without changing Shortcut data.confirm_archive=trueis required when archiving.confirm_delete=trueis required for delete operations (in addition toconfirm).Read tools do not support
dry_run; passing it returns a validation error.
Recommended flow for writes:
Run with
dry_run=trueand validate the payload.Re-run with
confirm="CONFIRM_WRITE"(andconfirm_archive=true/confirm_delete=trueif applicable).
Tools (73)
# | Tool | Description | Type |
Stories | |||
1 |
| Search stories with Shortcut query syntax | Read |
2 |
| Get a story by ID | Read |
3 |
| Create a story in a project | Write |
4 |
| Update fields on an existing story | Write |
5 |
| Permanently delete a story | Delete |
6 |
| Archive a story | Archive |
7 |
| Move a story to a workflow state by ID or name | Write |
8 |
| Get change history of a story | Read |
9 |
| Update multiple stories at once | Write |
10 |
| Move multiple stories to a different project/state | Write |
11 |
| Permanently delete multiple stories | Delete |
Story Comments | |||
12 |
| List comments for a story | Read |
13 |
| Add a comment to a story | Write |
14 |
| Update a comment on a story | Write |
15 |
| Delete a comment | Delete |
Story Tasks (Checklists) | |||
16 |
| List checklist tasks on a story | Read |
17 |
| Add a checklist task | Write |
18 |
| Update a checklist task (e.g. mark complete) | Write |
19 |
| Delete a checklist task | Delete |
Story Links | |||
20 |
| Link two stories (blocks, relates to, duplicates) | Write |
21 |
| Delete a story link | Delete |
Story Labels | |||
22 |
| Add a label to a story | Write |
23 |
| Remove a label from a story | Write |
Story VCS Integration | |||
24 |
| List Git branches associated with a story | Read |
25 |
| List Git commits associated with a story | Read |
26 |
| List pull requests associated with a story | Read |
27 |
| List external links on a story | Read |
Epics | |||
28 |
| List epics | Read |
29 |
| Get an epic by ID | Read |
30 |
| Create an epic | Write |
31 |
| Update an epic | Write |
32 |
| Permanently delete an epic | Delete |
33 |
| Archive an epic | Archive |
34 |
| Search epics with query syntax | Read |
35 |
| List stories in an epic | Read |
36 |
| Add a label to an epic | Write |
Epic Comments | |||
37 |
| List comments on an epic | Read |
38 |
| Add a comment to an epic | Write |
Iterations (Sprints) | |||
39 |
| List iterations | Read |
40 |
| Get an iteration by ID | Read |
41 |
| Create an iteration | Write |
42 |
| Update an iteration | Write |
43 |
| Permanently delete an iteration | Delete |
44 |
| List stories in an iteration | Read |
Milestones | |||
45 |
| List milestones | Read |
46 |
| Get a milestone by ID | Read |
47 |
| Create a milestone | Write |
48 |
| Update a milestone | Write |
49 |
| Permanently delete a milestone | Delete |
50 |
| List epics in a milestone | Read |
Projects | |||
51 |
| List projects | Read |
52 |
| Get a project by ID | Read |
53 |
| Create a project | Write |
54 |
| Update a project | Write |
55 |
| Permanently delete a project | Delete |
Labels | |||
56 |
| List all labels | Read |
57 |
| Get a label by ID | Read |
58 |
| Create a label | Write |
59 |
| Update a label | Write |
60 |
| Permanently delete a label | Delete |
Workflows | |||
61 |
| List all workflows and their states | Read |
Members & Groups | |||
62 |
| List workspace members | Read |
63 |
| Get a member by UUID | Read |
64 |
| List teams/groups | Read |
65 |
| Get a team/group by UUID | Read |
Linked Files | |||
66 |
| List all linked files | Read |
67 |
| Get a linked file by ID | Read |
68 |
| Create a linked file reference (e.g. Google Doc, Figma) | Write |
69 |
| Update a linked file | Write |
70 |
| Permanently delete a linked file | Delete |
Other | |||
71 |
| List all custom fields and their values | Read |
72 |
| List all story/epic templates | Read |
73 |
| List linked Git repositories | Read |
Type legend: Read = no confirmation needed | Write = requires confirm="CONFIRM_WRITE" | Delete = requires confirm_delete=true + confirm="CONFIRM_WRITE" | Archive = requires confirm_archive=true + confirm="CONFIRM_WRITE"
Example tool calls
Create a story (dry run first)
{
"name": "MCP integration test story",
"project_id": 101,
"story_type": "feature",
"description": "Created from Shortcut MCP server",
"dry_run": true
}Create a story (execute)
{
"name": "MCP integration test story",
"project_id": 101,
"story_type": "feature",
"description": "Created from Shortcut MCP server",
"confirm": "CONFIRM_WRITE"
}Transition a story to a new state
{
"story_id": 12345,
"workflow_state_name": "In Progress",
"workflow_name": "Engineering Workflow",
"confirm": "CONFIRM_WRITE"
}Update an epic
{
"epic_id": 14,
"state": "in progress",
"confirm": "CONFIRM_WRITE"
}Archive a story
{
"story_id": 12345,
"confirm_archive": true,
"confirm": "CONFIRM_WRITE"
}Delete a story (double confirmation)
{
"story_id": 12345,
"confirm_delete": true,
"confirm": "CONFIRM_WRITE"
}Bulk move stories
{
"story_ids": [123, 456, 789],
"project_id": 202,
"workflow_state_id": 500000010,
"confirm": "CONFIRM_WRITE"
}Search stories
{
"query": "owner:johndoe state:\"In Progress\" type:bug"
}Create an iteration
{
"name": "Sprint 42",
"start_date": "2025-03-10",
"end_date": "2025-03-24",
"confirm": "CONFIRM_WRITE"
}Link two stories
{
"subject_id": 123,
"object_id": 456,
"verb": "blocks",
"confirm": "CONFIRM_WRITE"
}Add a comment to a story
{
"story_id": 12345,
"text": "Looks good, moving to review.",
"confirm": "CONFIRM_WRITE"
}Using the test client
The included test client (src/client.ts) lets you test tools from the command line without an AI assistant:
# Build first
npm run build
# List all available tools
npm run client
# Read operations (no confirmation needed)
npm run client -- list_epics
npm run client -- get_story '{"story_id": 123}'
npm run client -- search_stories '{"query": "state:\"In Progress\""}'
npm run client -- list_workflows
# Write operations (need confirmation)
npm run client -- create_story '{"name": "Test", "project_id": 101, "dry_run": true}'
npm run client -- create_story '{"name": "Test", "project_id": 101, "confirm": "CONFIRM_WRITE"}'Project structure
shortcut-mcp-server/
├── src/
│ ├── index.ts # MCP server — all 73 tool registrations and Shortcut API logic
│ └── client.ts # Standalone test client for development
├── dist/ # Compiled JavaScript (generated by npm run build)
├── package.json
├── tsconfig.json
├── .env.example # Template for API token
└── .gitignoreLicense
MIT
Available Tools
73 toolsadd_epic_labelAdd Label to EpicB
Add a label to a Shortcut epic by providing the full set of label IDs.
Inputs: epic_id (required), label_ids (required), confirm, dry_run.
add_story_labelAdd Label to StoryA
Add a label to a Shortcut story by providing the full set of label IDs.
Inputs: story_id (required), label_ids (required), confirm, dry_run.
archive_epicArchive Shortcut EpicB
Archive a Shortcut epic. Requires confirm_archive=true and confirm='CONFIRM_WRITE'.
Inputs: epic_id (required), confirm, dry_run, confirm_archive.
archive_storyArchive Shortcut StoryA
Archive a Shortcut story. Requires confirm_archive=true and confirm='CONFIRM_WRITE'.
Inputs: story_id (required), confirm, dry_run, confirm_archive.
bulk_delete_storiesBulk Delete StoriesA
Permanently delete multiple stories at once. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: story_ids (required), confirm, dry_run, confirm_delete.
bulk_move_storiesBulk Move StoriesC
Move multiple stories to a different project and/or workflow state.
Inputs: story_ids (required), confirm, dry_run, epic_id, +2 more.
bulk_update_storiesBulk Update StoriesA
Update multiple stories at once. Provide story IDs and the fields to change on all of them.
Inputs: story_ids (required), confirm, dry_run, epic_id, +12 more.
create_epicCreate Shortcut EpicC
Create a new epic in Shortcut.
Inputs: name (required), confirm, dry_run, group_id, +4 more.
create_epic_commentCreate Epic CommentB
Create a comment on a Shortcut epic.
Inputs: text (required), epic_id (required), confirm, dry_run, +1 more.
create_iterationCreate Shortcut IterationC
Create a new iteration (sprint) in Shortcut.
Inputs: name (required), end_date (required), start_date (required), confirm, +5 more.
create_labelCreate Shortcut LabelC
Create a new label in Shortcut.
Inputs: name (required), color, confirm, dry_run, +2 more.
create_linked_fileCreate Linked FileB
Create a linked file reference in Shortcut (e.g. Google Doc, Figma link).
Inputs: url (required), name (required), type (required), confirm, +3 more.
create_milestoneCreate Shortcut MilestoneC
Create a new milestone in Shortcut.
Inputs: name (required), state, confirm, dry_run, +3 more.
create_projectCreate Shortcut ProjectC
Create a new project in Shortcut.
Inputs: name (required), color, confirm, dry_run, +3 more.
create_storyCreate Shortcut StoryC
Create a new Shortcut story in a project.
Inputs: name (required), project_id (required), confirm, dry_run, +11 more.
create_story_commentCreate Story CommentC
Create a comment on a Shortcut story.
Inputs: text (required), story_id (required), confirm, dry_run, +1 more.
create_story_linkCreate Story LinkC
Link two stories together (e.g. blocks, is blocked by, relates to, duplicates).
Inputs: verb (required), object_id (required), subject_id (required), confirm, +1 more.
create_story_taskCreate Story TaskC
Add a checklist task to a Shortcut story.
Inputs: story_id (required), description (required), confirm, dry_run, +2 more.
delete_epicDelete Shortcut EpicA
Permanently delete a Shortcut epic by ID. This is IRREVERSIBLE. Requires both confirm='CONFIRM_WRITE' and confirm_delete=true.
Inputs: epic_id (required), confirm, dry_run, confirm_delete.
delete_iterationDelete Shortcut IterationA
Permanently delete a Shortcut iteration. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: iteration_id (required), confirm, dry_run, confirm_delete.
delete_labelDelete Shortcut LabelA
Permanently delete a Shortcut label. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: label_id (required), confirm, dry_run, confirm_delete.
delete_linked_fileDelete Linked FileA
Permanently delete a linked file. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: linked_file_id (required), confirm, dry_run, confirm_delete.
delete_milestoneDelete Shortcut MilestoneA
Permanently delete a Shortcut milestone. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: milestone_id (required), confirm, dry_run, confirm_delete.
delete_projectDelete Shortcut ProjectA
Permanently delete a Shortcut project. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: project_id (required), confirm, dry_run, confirm_delete.
delete_storyDelete Shortcut StoryA
Permanently delete a Shortcut story by ID. This is IRREVERSIBLE. Requires both confirm='CONFIRM_WRITE' and confirm_delete=true.
Inputs: story_id (required), confirm, dry_run, confirm_delete.
delete_story_commentDelete Story CommentA
Permanently delete a comment on a Shortcut story. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: story_id (required), comment_id (required), confirm, dry_run, +1 more.
delete_story_linkDelete Story LinkA
Delete a link between two stories. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: story_link_id (required), confirm, dry_run, confirm_delete.
delete_story_taskDelete Story TaskA
Delete a checklist task from a Shortcut story. IRREVERSIBLE. Requires confirm_delete=true and confirm='CONFIRM_WRITE'.
Inputs: task_id (required), story_id (required), confirm, dry_run, +1 more.
get_epicGet Shortcut EpicB
Get a Shortcut epic by numeric epic ID.
Inputs: epic_id (required), dry_run.
get_groupGet Shortcut GroupB
Get a Shortcut team/group by UUID.
Inputs: group_id (required), dry_run.
get_iterationGet Shortcut IterationC
Get a Shortcut iteration by numeric iteration ID.
Inputs: iteration_id (required), dry_run.
get_iteration_storiesGet Iteration StoriesB
List all stories in a Shortcut iteration.
Inputs: iteration_id (required), dry_run.
get_labelGet Shortcut LabelB
Get a Shortcut label by numeric label ID.
Inputs: label_id (required), dry_run.
get_linked_fileGet Linked FileB
Get a linked file by numeric ID.
Inputs: linked_file_id (required), dry_run.
get_memberGet Shortcut MemberA
Get a Shortcut member by UUID.
Inputs: member_id (required), dry_run.
get_milestoneGet Shortcut MilestoneB
Get a Shortcut milestone by numeric milestone ID.
Inputs: milestone_id (required), dry_run.
get_projectGet Shortcut ProjectA
Get a Shortcut project by numeric project ID.
Inputs: project_id (required), dry_run.
get_storyGet Shortcut StoryB
Get a Shortcut story by numeric story ID.
Inputs: story_id (required), dry_run.
get_story_historyGet Story HistoryC
Get the change history of a Shortcut story.
Inputs: story_id (required), dry_run.
list_custom_fieldsList Shortcut Custom FieldsA
List all custom fields (e.g. Priority) and their possible values in your Shortcut workspace.
Inputs: dry_run.
list_entity_templatesList Entity TemplatesA
List all story/epic templates in your Shortcut workspace.
Inputs: dry_run.
list_epic_commentsList Epic CommentsB
List comments on a Shortcut epic.
Inputs: epic_id (required), dry_run.
list_epicsList Shortcut EpicsC
List epics in your Shortcut workspace.
Inputs: dry_run.
list_epic_storiesList Epic StoriesA
List all stories belonging to a Shortcut epic.
Inputs: epic_id (required), dry_run.
list_groupsList Shortcut GroupsB
List teams/groups in your Shortcut workspace.
Inputs: dry_run.
list_iterationsList Shortcut IterationsC
List iterations (sprints) in your Shortcut workspace.
Inputs: dry_run.
list_labelsList Shortcut LabelsC
List all labels in your Shortcut workspace.
Inputs: dry_run.
list_linked_filesList Linked FilesC
List all linked files in your Shortcut workspace.
Inputs: dry_run.
list_membersList Shortcut MembersB
List members in your Shortcut workspace.
Inputs: dry_run.
list_milestone_epicsList Milestone EpicsA
List all epics belonging to a Shortcut milestone.
Inputs: milestone_id (required), dry_run.
list_milestonesList Shortcut MilestonesC
List milestones in your Shortcut workspace.
Inputs: dry_run.
list_projectsList Shortcut ProjectsC
List projects in your Shortcut workspace.
Inputs: dry_run.
list_repositoriesList RepositoriesB
List all linked Git repositories in your Shortcut workspace.
Inputs: dry_run.
list_story_branchesList Story BranchesB
List Git branches associated with a Shortcut story.
Inputs: story_id (required), dry_run.
list_story_commentsList Story CommentsB
List comments for a Shortcut story.
Inputs: story_id (required), dry_run.
list_story_commitsList Story CommitsB
List Git commits associated with a Shortcut story.
Inputs: story_id (required), dry_run.
list_story_external_linksList Story External LinksC
List external links attached to a Shortcut story.
Inputs: story_id (required), dry_run.
list_story_pull_requestsList Story Pull RequestsA
List pull requests associated with a Shortcut story.
Inputs: story_id (required), dry_run.
list_story_tasksList Story TasksB
List checklist tasks on a Shortcut story.
Inputs: story_id (required), dry_run.
list_workflowsList Shortcut WorkflowsB
List all workflows in your Shortcut workspace.
Inputs: dry_run.
remove_story_labelRemove Label from StoryA
Remove a label from a Shortcut story. Provide the remaining label IDs after removal. Requires confirm='CONFIRM_WRITE'.
Inputs: story_id (required), label_ids (required), confirm, dry_run.
search_epicsSearch Shortcut EpicsC
Search Shortcut epics with query syntax.
Inputs: query (required), dry_run, page_size.
search_storiesSearch Shortcut StoriesC
Search Shortcut stories with Shortcut query syntax.
Inputs: query (required), dry_run, page_size.
transition_story_stateTransition Story StateB
Move a story to a new workflow state using either state ID or state name.
Inputs: story_id (required), confirm, dry_run, workflow_name, +2 more.
update_epicUpdate Shortcut EpicC
Update fields on an existing Shortcut epic.
Inputs: epic_id (required), name, state, confirm, +6 more.
update_iterationUpdate Shortcut IterationC
Update fields on an existing Shortcut iteration.
Inputs: iteration_id (required), name, confirm, dry_run, +6 more.
update_labelUpdate Shortcut LabelC
Update a label in Shortcut.
Inputs: label_id (required), name, color, confirm, +3 more.
update_linked_fileUpdate Linked FileC
Update a linked file in Shortcut.
Inputs: linked_file_id (required), url, name, type, +3 more.
update_milestoneUpdate Shortcut MilestoneC
Update fields on an existing Shortcut milestone.
Inputs: milestone_id (required), name, state, confirm, +6 more.
update_projectUpdate Shortcut ProjectC
Update fields on an existing Shortcut project.
Inputs: project_id (required), name, color, confirm, +5 more.
update_storyUpdate Shortcut StoryC
Update fields on an existing Shortcut story.
Inputs: story_id (required), name, confirm, dry_run, +8 more.
update_story_commentUpdate Story CommentC
Update the text of a comment on a Shortcut story.
Inputs: text (required), story_id (required), comment_id (required), confirm, +1 more.
update_story_taskUpdate Story TaskB
Update a checklist task on a Shortcut story (e.g. mark complete).
Inputs: task_id (required), story_id (required), confirm, dry_run, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 73 tools
Most tools are clearly distinct by resource and action (e.g., list_story_comments vs list_epic_comments). However, generic update_story overlaps with transition_story_state and add_story_label, which could cause misselection.
All tools follow a strict snake_case verb_noun pattern: list/get for reads, create/update/delete for writes, and resource-specific nouns. Even bulk operations and transition_story_state fit the pattern, with no mixed conventions.
With 73 tools, this server far exceeds the 50+ extreme threshold. The massive surface is likely to overwhelm agents and create unnecessary selection overhead, despite each tool potentially having a specific purpose.
The tool set provides comprehensive CRUD coverage for stories, epics, projects, iterations, milestones, labels, linked files, and comments, plus search and bulk operations. Minor gaps include no update/delete for epic comments and no remove_epic_label.
Maintenance
Related MCP Connectors
MCP server for generating rough-draft project plans from natural-language prompts.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A MCP server built for developers enabling Git based project management with project and personal…
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
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-

Shortcut MCP Serverofficial
AlicenseBqualityFmaintenanceA 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.569,994 npm96MIT- AlicenseBqualityDmaintenanceMCP server for interacting with Shortcut (project management) directly from Claude, enabling viewing, searching, and creating stories, epics, and objectives with safe read-only and create operations.18MIT
- AlicenseAqualityCmaintenanceMCP server for YouGile project management. Provides 57 tools covering 100% of YouGile API v2, enabling natural language management of projects, boards, columns, tasks, chats, users, and more.5774 npm10MIT