Shortcut

You can connect to Shortcut’s MCP server to manage Shortcut data and actions from your developer tools. This MCP server provides a set of endpoints and local runtime options so you can work with Shortcut stories, epics, iterations, projects, and more through familiar MCP clients and IDE integrations.

How to use

You can connect using either the remote HTTP MCP endpoint or a local runtime config that runs the MCP server on your machine. The HTTP option is the simplest start, while the local runtime lets you run the MCP server directly from your development environment.

How to install

Prerequisites: ensure you have Node.js and npm installed on your system. You may also use a local runtime command if you prefer running the MCP server directly from your environment.

1. Create or update your MCP configuration file at the default MCP path expected by your client (for example, a file named mcp.json under your home directory or project root, depending on your client). 2) Add the Shortcut MCP server configuration using one of the supported methods shown below. 3) Restart or reinitialize your MCP client to pick up the new server configuration.

Configuration and runtime options

Two primary ways to configure the Shortcut MCP server are available. You can point to a remote MCP server via HTTP or run a local MCP server process that your environment launches. The HTTP method connects to Shortcut’s hosted MCP endpoint. The local method uses a package you run with a command such as npx.

HTTP MCP configuration (remote server)

Use this configuration to connect to Shortcut’s hosted MCP server. This does not require an API token on your machine because authentication is handled by OAuth when you authorize through the client.

{
  "mcpServers": {
    "shortcut": {
      "url": "https://mcp.shortcut.com/mcp"
    }
  }
}

Local runtime MCP configuration (stdio)

If you prefer running the MCP server locally from your development environment, you can use a local runtime command. This example shows how to start the MCP server with npm/npx locally and pass required environment variables.

{
  "mcpServers": {
    "shortcut_run": {
      "command": "npx",
      "args": [
        "-y",
        "@shortcut/mcp@latest"
      ],
      "env": {
        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>",
        "SHORTCUT_TOOLS": "stories,epics,iterations-create"
      }
    }
  }
}

Starting with VS Code and Claude Desktop

If you use VS Code or Claude Desktop, you can point your mcp.json or VS Code MCP settings to the Shortcut MCP endpoint. You will be prompted to authorize with your Shortcut account on first use.

Other IDEs and local setups

If your IDE supports stdio-based MCP servers or you want to run the server locally, follow the local runtime approach described above and adjust the environment variables as needed for your development environment.

Available tools and capabilities

Access a wide range of Shortcut operations, including creating and updating stories, managing epics, handling iterations, labels, and custom fields, and querying documents and workflows. The exact tools you enable depend on your configuration and the MCP client you use.

Issues and Troubleshooting

Make sure you are running the latest version of the MCP server. If you encounter problems, consider trying the following options.

- Open an issue on the issue tracker
- Reach out for help via the designated team channel

Available tools

stories-get-by-id

Get a single Shortcut story by ID

stories-get-history

Get the change history for a story

stories-search

Find Shortcut stories with filtering and search options

stories-get-branch-name

Get the recommended branch name for a specific story

stories-create

Create a new Shortcut story

stories-update

Update an existing Shortcut story

stories-upload-file

Upload a file and link it to a story

stories-assign-current-user

Assign the current user as the owner of a story

stories-unassign-current-user

Unassign the current user as the owner of a story

stories-create-comment

Create a comment on a story

stories-create-subtask

Add a new sub-task to a story

stories-add-subtask

Add an existing story as a sub-task

stories-remove-subtask

Remove a sub-task from a story

stories-add-task

Add a task to a story

stories-update-task

Update a task in a story

stories-add-relation

Add a story relationship (relates to, blocks, duplicates, etc.)

stories-add-external-link

Add an external link to a Shortcut story

stories-remove-external-link

Remove an external link from a Shortcut story

stories-set-external-links

Replace all external links on a story with a new set of links

stories-get-by-external-link

Find all stories that contain a specific external link

labels-list

List all labels in the Shortcut workspace

labels-get-stories

Get all stories with a specific label

labels-create

Create a new label in Shortcut

custom-fields-list

List all custom fields in the workspace with their possible values

epics-get-by-id

Get a Shortcut epic by ID

epics-search

Find Shortcut epics with filtering and search options

epics-create

Create a new Shortcut epic

epics-update

Update an existing Shortcut epic

epics-delete

Delete a Shortcut epic

iterations-get-stories

Get stories in a specific iteration by iteration ID

iterations-get-by-id

Get a Shortcut iteration by ID

iterations-search

Find Shortcut iterations with filtering and search options

iterations-create

Create a new Shortcut iteration with start/end dates

iterations-update

Update an existing Shortcut iteration

iterations-delete

Delete a Shortcut iteration

iterations-get-active

Get active iterations for the current user based on team memberships

iterations-get-upcoming

Get upcoming iterations for the current user based on team memberships

objectives-get-by-id

Get a Shortcut objective by ID

objectives-search

Find Shortcut objectives with filtering and search options

teams-get-by-id

Get a Shortcut team by ID

teams-list

List all Shortcut teams

projects-list

List all projects in the Shortcut workspace

projects-get-by-id

Get a Shortcut project by public ID

projects-get-stories

Get all stories in a specific project

workflows-get-default

Get the default workflow for a specific team or the workspace default

workflows-get-by-id

Get a Shortcut workflow by ID

workflows-list

List all Shortcut workflows

users-get-current

Get the current user information

users-get-current-teams

Get a list of teams where the current user is a member

users-list

Get all workspace users

documents-create

Create a new document in Shortcut with Markdown content

documents-update

Update content of an existing document by its ID

documents-list

List all documents in Shortcut

documents-search

Search for documents

documents-get-by-id

Retrieve a specific document in markdown format by its ID