Skip to main content
Glama
Shortcut MCP Server

Shortcut MCP Server

by ampcome-mcps

@shortcut/mcp

Version Monthly Downloads GitHub License PRs welcome! X

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

Install MCP Server

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

Related MCP server: Shortcut.com MCP Server

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.

Available Tools

33 tools
add-external-link-to-storyC

Add an external link to a Shortcut story

Inputs: storyPublicId (required), externalLink (required).

add-relation-to-storyC

Add a story relationship to a story

Inputs: storyPublicId (required), relatedStoryPublicId (required), relationshipType.

add-task-to-storyC

Add a task to a story

Inputs: storyPublicId (required), taskDescription (required), taskOwnerIds.

assign-current-user-as-ownerC

Assign the current user as the owner of a story

Inputs: storyPublicId (required).

create-documentA

Create a new document in Shortcut with a title and content. Returns the document's id, title, and app_url. Note: Use HTML markup for the content (e.g., , , , ) rather than Markdown.

Inputs: title (required), content (required).

create-epicC

Create a new Shortcut epic.

Inputs: name (required), owner, description, teamId.

create-iterationC

Create a new Shortcut iteration

Inputs: name (required), startDate (required), endDate (required), teamId, +1 more.

create-storyA

Create a new Shortcut story. Name is required, and either a Team or Workflow must be specified:

  • If only Team is specified, we will use the default workflow for that team.

  • If Workflow is specified, it will be used regardless of Team. The story will be added to the default state for the workflow.

Inputs: name (required), description, type, owner, +4 more.

create-story-commentC

Create a comment on a story

Inputs: storyPublicId (required), text (required).

get-active-iterationsB

Get the active Shortcut iterations for the current user based on their team memberships

Inputs: teamId.

get-current-userB

Get the current user

Inputs: no named parameters.

get-epicB

Get a Shortcut epic by public ID

Inputs: epicPublicId (required).

get-iterationB

Get a Shortcut iteration by public ID

Inputs: iterationPublicId (required).

get-iteration-storiesC

Get stories in a specific iteration by iteration public ID

Inputs: iterationPublicId (required), includeStoryDescriptions.

get-objectiveC

Get a Shortcut objective by public ID

Inputs: objectivePublicId (required).

get-storyC

Get a Shortcut story by public ID

Inputs: storyPublicId (required).

get-story-branch-nameC

Get a valid branch name for a specific story.

Inputs: storyPublicId (required).

get-teamB

Get a Shortcut team by public ID

Inputs: teamPublicId (required).

get-upcoming-iterationsB

Get the upcoming Shortcut iterations for the current user based on their team memberships

Inputs: teamId.

get-workflowC

Get a Shortcut workflow by public ID

Inputs: workflowPublicId (required).

list-membersC

Get all members

Inputs: no named parameters.

list-teamsB

List all Shortcut teams

Inputs: no named parameters.

list-workflowsB

List all Shortcut workflows

Inputs: no named parameters.

remove-external-link-from-storyC

Remove an external link from a Shortcut story

Inputs: storyPublicId (required), externalLink (required).

search-epicsC

Find Shortcut epics.

Inputs: id, name, description, state, +18 more.

search-iterationsC

Find Shortcut iterations.

Inputs: id, name, description, state, +5 more.

search-objectivesC

Find Shortcut objectives.

Inputs: id, name, description, state, +11 more.

search-storiesC

Find Shortcut stories.

Inputs: id, name, description, comment, +40 more.

set-story-external-linksC

Replace all external links on a story with a new set of links

Inputs: storyPublicId (required), externalLinks (required).

unassign-current-user-as-ownerC

Unassign the current user as the owner of a story

Inputs: storyPublicId (required).

update-storyC

Update an existing Shortcut story. Only provide fields you want to update. The story public ID will always be included in updates.

Inputs: storyPublicId (required), name, description, type, +6 more.

update-taskC

Update a task in a story

Inputs: storyPublicId (required), taskPublicId (required), taskDescription, taskOwnerIds, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 33 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting specific resources and actions in Shortcut, such as stories, epics, iterations, and users. There is no significant overlap; for example, 'create-story' and 'update-story' are distinct, and 'add-external-link-to-story' and 'set-story-external-links' serve different functions (add vs. replace).

    Naming Consistency4/5

    Tool names follow a consistent verb-object pattern with hyphens (e.g., 'create-story', 'get-iteration'), making them readable and predictable. Minor deviations exist, such as 'assign-current-user-as-owner' being more verbose, but overall, the naming is highly consistent across the set.

    Tool Count3/5

    With 33 tools, the count is borderline high for a project management server, potentially overwhelming for agents. While it covers many operations, it might be slightly heavy compared to typical well-scoped servers (3-15 tools), though not extreme.

    Completeness5/5

    The tool set provides comprehensive CRUD and lifecycle coverage for Shortcut's domain, including stories, epics, iterations, documents, and users. It supports creation, retrieval, updating, deletion (via removal tools), and search operations, with no obvious gaps for core workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers