Shortcut MCP Server

What is Shortcut MCP Server about?

The server implements a set of MCP tools for Shortcut, exposing endpoints that allow AI models to retrieve, create, update, and delete Shortcut entities (stories, epics, iterations, objectives, teams, workflows, users, documents). It enables seamless integration of AI assistants into the Shortcut workflow.

How to use Shortcut MCP Server?

Install the package via npx (no global install required).

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

Add the configuration to the MCP configuration file of your AI tool (Windsurf, Cursor, Claude Code, Zed, etc.).
Ensure the SHORTCUT_API_TOKEN environment variable contains a valid Shortcut API token.
Optionally limit tools with SHORTCUT_TOOLS or enable read‑only mode with SHORTCUT_READONLY=true.
Restart the AI assistant to load the new server.

Key features of Shortcut MCP Server

Comprehensive tool set covering stories, epics, iterations, objectives, teams, workflows, users, and documents.
Create, read, update, delete operations for most Shortcut entities.
Branch name generation based on workspace settings.
File upload linked directly to stories.
Tool filtering via SHORTCUT_TOOLS to expose only needed functions.
Read‑only mode to protect data when only retrieval is required.
Works with multiple AI platforms (Windsurf, Cursor, Claude Code, Zed) using the same MCP configuration.

Use cases of Shortcut MCP Server

AI‑driven ticket triage: An assistant can fetch unassigned stories, suggest owners, or automatically assign the current user.
Automated sprint planning: Retrieve active or upcoming iterations and populate them with stories based on priority.
Documentation generation: Pull story details and generate release notes or project summaries.
Context‑aware coding assistance: Provide the LLM with the current story’s description, tasks, and related files while coding.
Metrics dashboards: Aggregate story statuses, epic progress, or iteration velocity for reporting.

FAQ from the Shortcut MCP Server

Q: Do I need to install the package globally? A: No. The recommended approach is to run it with npx, which downloads and executes the latest version on demand.

Q: Which environment variable supplies the Shortcut token? A: SHORTCUT_API_TOKEN must contain a valid Shortcut API token with the required scopes.

Q: Can I limit the tools exposed to the LLM? A: Yes. Set SHORTCUT_TOOLS to a comma‑separated list of entities (e.g., stories,epics) or specific tool names (e.g., stories-get-by-id).

Q: How do I enable read‑only mode? A: Add SHORTCUT_READONLY=true to the server’s environment variables; all mutating tools become unavailable.

Q: What if the NPX command fails when using a version manager like MISE? A: Install the MISE VS Code extension or ensure the Node version used by NPX matches the one expected by the project.

Q: Where should the mcp.json configuration be placed? A: For Cursor – ~/.cursor/mcp.json or .cursor/mcp.json in the project root. For Windsurf – the MCP Configuration Panel. For Claude Code – ~/.claude.json. For Zed – settings.json under context_servers.

@shortcut/mcp

The MCP server for Shortcut.

Usage

Windsurf

See the official Windsurf docs for more information.

Open the Windsurf MCP Configuration Panel
Click Add custom server.
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.

You can add a new MCP server from the Claude Code CLI. But modifying the json file directly is simpler!

You can either add a new MCP server from the command line:

# Grab your Shortcut token here: https://app.shortcut.com/settings/account/api-tokens
claude mcp add shortcut --transport=stdio -e API_KEY=$SHORTCUT_API_TOKEN -- npx -y @shortcut/mcp@latest

Or you can edit the local JSON file directly:

Open the Claude Code configuration file (it should be in ~/.claude.json).
Find the projects > mcpServers section and add the following details and save the file:

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

Zed

Zed MCP Documentation

Open your settings.json file. Instructions here
Add the following details and save the file:

  "context_servers": {
    "shortcut": {
      "settings":{},
      "command": {
        "path": "<PATH/TO/NPX>",
        "args": [
          "-y",
          "@shortcut/mcp@latest"
        ],
        "env": {
          "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
        }
      }
    }
  }

Available Tools

Stories

stories-get-by-id - Get a single Shortcut story by ID
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-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

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

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

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 HTML content

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:

{
  "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
objectives
teams
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:

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

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

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.