@shortcut/mcp

The MCP server for Shortcut.

Usage

The only required input is your Shortcut API token. You can find it in your Shortcut account settings.

Once you have a valid token, you can pass it to the MCP server as an environement variable or a CLI argument.

Examples:

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

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

Due to an issue in gemini-cli that redacts environment variables that contain the word "token", you can also use the alternative name SHORTCUT_API_TKN instead of SHORTCUT_API_TOKEN. This works for both the environment variable and the CLI argument:

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

"shortcut": {
  "command": "npx",
  "args": [
    "-y",
    "@shortcut/mcp@latest",
    "SHORTCUT_API_TKN=<YOUR_SHORTCUT_API_TOKEN>"
  ]
}

For more information on how to setup the MCP for your tool of choice, see below.

Windsurf

See the official Windsurf docs for more information.

Open the MCP configuration by clicking the MCPs icon in the Cascade panel, or navigate to Windsurf Settings > Cascade > MCP Servers.
Click Add Custom Server to edit the raw mcp_config.json file (located at ~/.codeium/windsurf/mcp_config.json).
Add the following details and save the file:

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

Cursor

See the official Cursor docs for more information.

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).
Add the following details and save the file:

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

Claude Code

See the official Claude Code docs for more information.

Add the MCP server from the command line:

claude mcp add shortcut --transport stdio -e SHORTCUT_API_TOKEN=$SHORTCUT_API_TOKEN -- npx -y @shortcut/mcp@latest

Or you can create a .mcp.json file in your project root to share with your team:

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

Zed

See the official Zed MCP docs for more information.

Open your settings.json file. Instructions here.
Add the following to the context_servers section and save the file:

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

VS Code

See the official VS Code MCP docs for more information.

Create (or open) the .vscode/mcp.json file in your workspace.
Add the following details and save the file:

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

OpenCode

See the official OpenCode MCP docs for more information.

Add the following to your opencode.json configuration file:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shortcut": {
      "type": "local",
      "command": ["npx", "-y", "@shortcut/mcp@latest"],
      "environment": {
        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
      }
    }
  }
}

Available Tools

Stories

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

labels-list - List all labels in the Shortcut workspace.
labels-create - Create a new label in Shortcut.

Custom Fields

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

Epics

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

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

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

Teams

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

Projects

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

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

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

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.

[!NOTE] By default, all tools are enabled.

Example:

{
  "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.

[!TIP] Shortcut supports read-only API tokens, which you can use to ensure that the MCP server is limited to read-only operations at the API level. This provides an additional layer of security since the restriction is enforced by the Shortcut API itself, not just the MCP server. You can create a read-only token from your Shortcut API tokens settings.

Example:

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

Issues and Troubleshooting

[!IMPORTANT] 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:

Open an issue on GitHub
Ask for help in the community Slack

You can also check the list of common issues below to see if there is a known solution already.

Common Issues and Solutions

MCP fails on startup in Gemini CLI

If you are using the Gemini CLI and the MCP fails with the following error: ✕ Error during discovery for MCP server 'shortcut': MCP error -32000: Connection closed, it might be due to an issue in Gemini where it redacts environment variables that contain the word token. You can either pass the Shortcut token as a CLI argument, or use the alternative name SHORTCUT_API_TKN instead of SHORTCUT_API_TOKEN. See the Usage section for more information.

NPX command not working when using MISE for version management

If you are using MISE for managing Node and NPM versions, you may encounter a "Client closed" error when trying to run the MCP server. Installing this extension into your IDE might help: https://github.com/hverlin/mise-vscode/.

Development

Installation

npm install

Build

npm run build

Running the Development Server Locally

To test your local development version of the MCP server rather than using the published package, follow these steps:

Build the project:
```
npm run build
```

Create or modify your mcp.json file to reference your local build:

{
  "mcpServers": {
    "shortcut": {
      "command": "node",
      "args": [
        "/path/to/your/local/mcp-server-shortcut/dist/index.js"
      ],
      "env": {
        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
      }
    }
  }
}

Place this mcp.json file in one of the following locations:
- For Cursor: In your home directory (~/.cursor/mcp.json) or in your project directory (.cursor/mcp.json)
- For Windsurf: Use the MCP Configuration Panel to add the custom server
Restart your AI assistant (Cursor or Windsurf) to load the new configuration.

This allows you to instantly test changes to the MCP server without having to publish a new version.

Shortcut