@shortcut/mcp

MCP Server for Shortcut users.

Links: Local Installations | Server Developers

Usage

Cursor

The fastest way to get started is to connect to Shortcut's hosted MCP server. No API token or local setup required — authentication is handled via OAuth.

1. Open (or create) the mcp.json file (it should be in ~/.cursor/mcp.json or <project-root>/.cursor/mcp.json, but see Cursor docs for more details).
2. Add the following details and save the file:

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

3. Restart Cursor. You will be prompted to authorize with your Shortcut account on first use.

VS Code

If all you need need the configuration for the mcp.json file use this. You will be prompted to authorize with your Shortcut account on first use.

{
  "servers": {
    "shortcut-mcp": {
      "type": "http",
      "url": "https://mcp.shortcut.com/mcp"
    }
  }
}

For more detail on installing MCP services in VSCode see the official VS Code MCP docs for more information.

Claude Desktop

Download the package from this repo

Then, either double-click the icon to install or drag the package onto the client window. It should trigger the installation.

Other IDEs / Running Locally

If your IDE doesn't support HTTP-based MCP servers, or you'd prefer to run the server locally, see the Local Server Setup guide. This covers setup for Windsurf, Zed, Claude Code, and any IDE that supports stdio-based MCP servers.

Available Tools

Stories

| Tool | Description | |------|-------------| | 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 (based on workspace settings) 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

| Tool | Description | |------|-------------| | 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

| Tool | Description | |------|-------------| | custom-fields-list | List all custom fields in the workspace with their possible values |

Epics

| Tool | Description | |------|-------------| | 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 | | epics-create-comment | Create a comment on an epic |

Iterations

| Tool | Description | |------|-------------| | 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

| Tool | Description | |------|-------------| | objectives-get-by-id | Get a Shortcut objective by ID | | objectives-search | Find Shortcut objectives with filtering and search options |

Teams

| Tool | Description | |------|-------------| | teams-get-by-id | Get a Shortcut team by ID | | teams-list | List all Shortcut teams |

Projects

| Tool | Description | |------|-------------| | 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

| Tool | Description | |------|-------------| | 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

| Tool | Description | |------|-------------| | 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

| Tool | Description | |------|-------------| | 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 |

Limit tools

You can limit the tools available to the LLM by setting the SHORTCUT_TOOLS environment variable to a comma-separated list.

• Tools can be limited by entity type by just adding the entity, eg stories or epics.
• Individual tools can also be limitied by their full name, eg stories-get-by-id or epics-search.

By default, all tools are enabled.

Example (when running locally):

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

The following values are accepted in addition to the full tool names listed above under Available Tools:

• users
• stories
• epics
• iterations
• labels
• custom-fields
• objectives
• teams
• projects
• workflows
• documents

Read-only mode

You can run the MCP server in read-only mode by setting the SHORTCUT_READONLY environment variable to true. This will disable all tools that modify data in Shortcut.

Example (when running locally):

{
  "mcpServers": {
    "shortcut": {
      "command": "npx",
      "args": [
        "-y",
        "@shortcut/mcp@latest"
      ],
      "env": {
        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>",
        "SHORTCUT_READONLY": "true"
      }
    }
  }
}

Issues and Troubleshooting

Before doing anything else, please make sure you are running the latest version!

If you run into problems using this MCP server, you have a couple of options:

| Option | Link | |--------|------| | Open an issue | GitHub | | Ask for help | Slack |