Shortcut MCP server
Shortcut's official MCP server: find, create, and update Stories, Epics, Iterations, Objectives, and Docs from your agent.
The Shortcut MCP server is Shortcut's official integration that lets an AI agent operate on your Shortcut workspace. Its center of gravity is Stories: an agent can search and read stories, get a story's change history, create and update stories, post comments, manage tasks and subtasks, add relations (relates-to, blocks, duplicates), attach and manage external links, upload files, and assign or unassign the current user. A handy stories-get-branch-name tool returns the workspace-conventional branch name so an agent can turn a ticket into a branch and a draft PR without leaving the editor.
Beyond stories it covers the rest of the planning hierarchy — epics, iterations (including active and upcoming iterations for the current user), objectives, projects, workflows, teams, labels, and custom fields — plus Docs, with tools to create, update, list, search, and read documents in markdown. The fastest deployment is Shortcut's hosted remote endpoint at https://mcp.shortcut.com/mcp with OAuth, so there is no API token or local setup. For clients without HTTP transport support it also runs locally over stdio via npx @shortcut/mcp using a SHORTCUT_API_TOKEN, with optional read-only and tool-limiting modes.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"shortcut": {
"type": "http",
"url": "https://mcp.shortcut.com/mcp"
}
}
}claude mcp add --transport http shortcut https://mcp.shortcut.com/mcpHeads up
- First tool call opens a browser to authorize.
Available tools
| Tool | Description |
|---|---|
| stories-get-by-id | Retrieves a single story by its identifier. |
| stories-get-history | Retrieves the change history for a story. |
| stories-search | Finds stories with filtering and search. |
| stories-get-branch-name | Gets the recommended branch name for a story based on workspace settings. |
| stories-create | Creates a new story. |
| stories-update | Modifies an existing story. |
| stories-upload-file | Uploads and links a file to a story. |
| stories-assign-current-user | Assigns the current user as a story owner. |
| stories-unassign-current-user | Removes the current user as a story owner. |
| stories-create-comment | Adds a comment to a story. |
| stories-create-subtask | Adds a new sub-task to a story. |
| stories-add-subtask | Links an existing story as a sub-task. |
| stories-remove-subtask | Unlinks a sub-task from a story. |
| stories-add-task | Adds a task to a story. |
| stories-update-task | Modifies a task in a story. |
| stories-add-relation | Creates a story relationship such as relates-to, blocks, or duplicates. |
| stories-add-external-link | Adds an external link to a story. |
| stories-remove-external-link | Removes an external link from a story. |
| stories-set-external-links | Replaces all external links on a story with a new set. |
| stories-get-by-external-link | Finds stories containing a specific external link. |
| labels-list | Lists all workspace labels. |
| labels-get-stories | Gets stories with a specific label. |
| labels-create | Creates a new label. |
| custom-fields-list | Lists all custom fields with their possible values. |
| epics-get-by-id | Retrieves an epic by its identifier. |
| epics-search | Finds epics with filtering and search. |
| epics-create | Creates a new epic. |
| epics-update | Modifies an existing epic. |
| epics-delete | Deletes an epic. |
| epics-create-comment | Adds a comment to an epic. |
| iterations-get-stories | Gets the stories in a specific iteration. |
| iterations-get-by-id | Retrieves an iteration by its identifier. |
| iterations-search | Finds iterations with filtering. |
| iterations-create | Creates an iteration with start and end dates. |
| iterations-update | Modifies an existing iteration. |
| iterations-delete | Deletes an iteration. |
| iterations-get-active | Gets the active iterations for the current user. |
| iterations-get-upcoming | Gets the upcoming iterations for the current user. |
| objectives-get-by-id | Retrieves an objective by its identifier. |
| objectives-search | Finds objectives with filtering. |
| teams-get-by-id | Retrieves a team by its identifier. |
| teams-list | Lists all workspace teams. |
| projects-list | Lists all workspace projects. |
| projects-get-by-id | Retrieves a project by its public identifier. |
| projects-get-stories | Gets all stories in a project. |
| workflows-get-default | Gets the default workflow for a team or workspace. |
| workflows-get-by-id | Retrieves a workflow by its identifier. |
| workflows-list | Lists all workspace workflows. |
| users-get-current | Gets information about the current user. |
| users-get-current-teams | Gets the teams the current user is a member of. |
| users-list | Gets all workspace users. |
| documents-create | Creates a document with markdown content. |
| documents-update | Updates a document's content. |
| documents-list | Lists all workspace documents. |
| documents-search | Searches for documents. |
| documents-get-by-id | Retrieves a document in markdown format. |
Required configuration
- SHORTCUT_API_TOKENRequired
Your Shortcut API token, created under Settings > API Tokens. Required for local stdio mode.
- SHORTCUT_READONLYOptional
Set to true to disable all data-modifying tools, leaving only read access.
- SHORTCUT_TOOLSOptional
Comma-separated list of tool names to expose, restricting the server's surface.
What you can do with it
Turn a Shortcut story into a branch and PR
The agent reads the story, uses stories-get-branch-name to follow your workspace naming convention, and scaffolds the branch and a draft PR, then updates the story as work ships.
Plan and report on an iteration
Ask the agent for the active iteration's stories, summarize progress, file new stories with the right epic and labels, and post a status update without leaving your editor.
FAQ
- Is it free?
- Yes. The server is free and open source under the useshortcut organization; it works within your existing Shortcut plan and its API limits, and you pay only for Shortcut itself.
- Does it support remote/OAuth?
- Yes. The fastest deployment is Shortcut's hosted remote endpoint at https://mcp.shortcut.com/mcp using OAuth, with no API token or local setup. A local stdio mode via npx @shortcut/mcp using a SHORTCUT_API_TOKEN is also available.
- Can I restrict it to read-only?
- Yes. Set SHORTCUT_READONLY=true to disable every data-modifying tool, or use SHORTCUT_TOOLS to expose only an explicit list of tool names.