Which integrations are available for this 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.

How do I use Shortcut MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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

by ptamb3

Overview Schema Related Servers Score Discussions

TypeScript

Remote

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 install

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.

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:

Run with dry_run=true and validate the payload.
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"
}

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

License

MIT

This server cannot be installed

license - not found

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ptamb3/shortcut-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server