@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

Labels

Custom Fields

Epics

Iterations

Objectives

Teams

Projects

Workflows

Users

Documents

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: