Shortcut MCP

What is Shortcut MCP about?

Shortcut MCP is a Model Context Protocol (MCP) server that enables AI assistants such as Windsurf, Cursor, Claude Code, and Zed to interact with Shortcut's project management data directly from the IDE or AI workspace.

How to use Shortcut MCP?

1. Install the server via npm (recommended command: npx -y @shortcut/mcp@latest).
2. Add the server configuration to the MCP settings file of your AI tool (e.g., mcp.json for Windsurf/Cursor, ~/.claude.json for Claude Code, or settings.json for Zed).
3. Provide a valid SHORTCUT_API_TOKEN in the environment section of the configuration.
4. Restart the AI assistant to load the new server configuration.

Key features of Shortcut MCP

• One‑line installation with npx – no global install required.
• Works across multiple AI platforms (Windsurf, Cursor, Claude Code, Zed).
• Secure token‑based authentication using Shortcut API token.
• Simple JSON‑based configuration that can be placed in project or home directories.
• Supports local development by pointing to a built dist/index.js file.

Use cases of Shortcut MCP

• Retrieve stories, epics, and tasks from Shortcut while coding to keep context up‑to‑date.
• Create or update Shortcut items directly from AI‑generated suggestions.
• Automate sprint planning or backlog grooming through AI assistants.
• Prototype workflow automations without writing custom integration code.

FAQ from the Shortcut MCP

Q: Do I need to publish the package to use it locally? A: No. Build the project locally and reference the dist/index.js file in the command/args section.

Q: Which environment variable is required? A: SHORTCUT_API_TOKEN – generate it in your Shortcut account settings.

Q: What if npx fails because of version managers like MISE? A: Install the MISE VS Code extension or ensure the correct Node/NPM version is active before running the server.

Q: How do I update to the latest version? A: Run the npx -y @shortcut/mcp@latest command again; the server pulls the newest package automatically.

@shortcut/mcp

The MCP server for Shortcut.

Usage

Windsurf

See the official Windsurf docs for more information.

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

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

1. Open the Claude Code configuration file (it should be in ~/.claude.json).
2. 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

1. Open your settings.json file. Instructions here
2. 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>"
        }
      }
    }
  }

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:

1. Build the project:

   npm run build
   

2. 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>"
         }
       }
     }
   }
   

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

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