Skip to main content
Glama
Shortcut MCP Server

Shortcut MCP Server

by ptamb3

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

  1. Install dependencies:

npm install
  1. Set your API token:

cp .env.example .env
# then edit .env and set SHORTCUT_API_TOKEN to your Shortcut API token

Or export directly:

export SHORTCUT_API_TOKEN="<your-token>"

You can generate a Shortcut API token at Settings → API Tokens in your Shortcut workspace.

  1. Build:

npm run build

Run

npm start

Integration

Claude Desktop

Add the following to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.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-server with 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=true returns the exact request payload without changing Shortcut data.

  • confirm_archive=true is required when archiving.

  • confirm_delete=true is required for delete operations (in addition to confirm).

  • Read tools do not support dry_run; passing it returns a validation error.

Recommended flow for writes:

  1. Run with dry_run=true and validate the payload.

  2. Re-run with confirm="CONFIRM_WRITE" (and confirm_archive=true / confirm_delete=true if applicable).

Tools (73)

#

Tool

Description

Type

Stories

1

search_stories

Search stories with Shortcut query syntax

Read

2

get_story

Get a story by ID

Read

3

create_story

Create a story in a project

Write

4

update_story

Update fields on an existing story

Write

5

delete_story

Permanently delete a story

Delete

6

archive_story

Archive a story

Archive

7

transition_story_state

Move a story to a workflow state by ID or name

Write

8

get_story_history

Get change history of a story

Read

9

bulk_update_stories

Update multiple stories at once

Write

10

bulk_move_stories

Move multiple stories to a different project/state

Write

11

bulk_delete_stories

Permanently delete multiple stories

Delete

Story Comments

12

list_story_comments

List comments for a story

Read

13

create_story_comment

Add a comment to a story

Write

14

update_story_comment

Update a comment on a story

Write

15

delete_story_comment

Delete a comment

Delete

Story Tasks (Checklists)

16

list_story_tasks

List checklist tasks on a story

Read

17

create_story_task

Add a checklist task

Write

18

update_story_task

Update a checklist task (e.g. mark complete)

Write

19

delete_story_task

Delete a checklist task

Delete

Story Links

20

create_story_link

Link two stories (blocks, relates to, duplicates)

Write

21

delete_story_link

Delete a story link

Delete

Story Labels

22

add_story_label

Add a label to a story

Write

23

remove_story_label

Remove a label from a story

Write

Story VCS Integration

24

list_story_branches

List Git branches associated with a story

Read

25

list_story_commits

List Git commits associated with a story

Read

26

list_story_pull_requests

List pull requests associated with a story

Read

27

list_story_external_links

List external links on a story

Read

Epics

28

list_epics

List epics

Read

29

get_epic

Get an epic by ID

Read

30

create_epic

Create an epic

Write

31

update_epic

Update an epic

Write

32

delete_epic

Permanently delete an epic

Delete

33

archive_epic

Archive an epic

Archive

34

search_epics

Search epics with query syntax

Read

35

list_epic_stories

List stories in an epic

Read

36

add_epic_label

Add a label to an epic

Write

Epic Comments

37

list_epic_comments

List comments on an epic

Read

38

create_epic_comment

Add a comment to an epic

Write

Iterations (Sprints)

39

list_iterations

List iterations

Read

40

get_iteration

Get an iteration by ID

Read

41

create_iteration

Create an iteration

Write

42

update_iteration

Update an iteration

Write

43

delete_iteration

Permanently delete an iteration

Delete

44

get_iteration_stories

List stories in an iteration

Read

Milestones

45

list_milestones

List milestones

Read

46

get_milestone

Get a milestone by ID

Read

47

create_milestone

Create a milestone

Write

48

update_milestone

Update a milestone

Write

49

delete_milestone

Permanently delete a milestone

Delete

50

list_milestone_epics

List epics in a milestone

Read

Projects

51

list_projects

List projects

Read

52

get_project

Get a project by ID

Read

53

create_project

Create a project

Write

54

update_project

Update a project

Write

55

delete_project

Permanently delete a project

Delete

Labels

56

list_labels

List all labels

Read

57

get_label

Get a label by ID

Read

58

create_label

Create a label

Write

59

update_label

Update a label

Write

60

delete_label

Permanently delete a label

Delete

Workflows

61

list_workflows

List all workflows and their states

Read

Members & Groups

62

list_members

List workspace members

Read

63

get_member

Get a member by UUID

Read

64

list_groups

List teams/groups

Read

65

get_group

Get a team/group by UUID

Read

Linked Files

66

list_linked_files

List all linked files

Read

67

get_linked_file

Get a linked file by ID

Read

68

create_linked_file

Create a linked file reference (e.g. Google Doc, Figma)

Write

69

update_linked_file

Update a linked file

Write

70

delete_linked_file

Permanently delete a linked file

Delete

Other

71

list_custom_fields

List all custom fields and their values

Read

72

list_entity_templates

List all story/epic templates

Read

73

list_repositories

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"
}
{
  "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
└── .gitignore

License

MIT

Available Tools

73 tools
add_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

    B3/5.0

    Scored across 73 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count1/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP 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.
      18
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      MCP 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.
      57
      74 npm
      10
      MIT