The MCP server for Shortcut.

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

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

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:

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

• get-story - Get a single Shortcut story by ID
• search-stories - Find Shortcut stories with filtering and search options
• get-story-branch-name - Get the recommended branch name (based on workspace settings) for a specific story.
• create-story - Create a new Shortcut story
• update-story - Update an existing Shortcut story
• upload-file-to-story - Upload a file and link it to a story
• assign-current-user-as-owner - Assign the current user as the owner of a story
• unassign-current-user-as-owner - Unassign the current user as the owner of a story
• create-story-comment - Create a comment on a story
• add-task-to-story - Add a task to a story
• update-task - Update a task in a story
• add-relation-to-story - Add a story relationship (relates to, blocks, duplicates, etc.)
• add-external-link-to-story - Add an external link to a Shortcut story
• remove-external-link-from-story - Remove an external link from a Shortcut story
• set-story-external-links - Replace all external links on a story with a new set of links
• get-stories-by-external-link - Find all stories that contain a specific external link

• get-epic - Get a Shortcut epic by ID
• search-epics - Find Shortcut epics with filtering and search options
• create-epic - Create a new Shortcut epic

• get-iteration-stories - Get stories in a specific iteration by iteration ID
• get-iteration - Get a Shortcut iteration by ID
• search-iterations - Find Shortcut iterations with filtering and search options
• create-iteration - Create a new Shortcut iteration with start/end dates
• get-active-iterations - Get active iterations for the current user based on team memberships
• get-upcoming-iterations - Get upcoming iterations for the current user based on team memberships

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

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

• get-default-workflow - Get the default workflow for a specific team or the workspace default
• get-workflow - Get a Shortcut workflow by ID
• list-workflows - List all Shortcut workflows

• get-current-user - Get the current user information
• get-current-user-teams - Get a list of teams where the current user is a member
• list-users - Get all workspace users

• create-document - Create a new document in Shortcut with HTML content

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

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.

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

npm install

npm run build

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.