Skip to main content
Glama
Shortcut MCP Server

Shortcut MCP Server

Official
by useshortcut

@shortcut/mcp

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

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

56 tools
custom-fields-listCustom: Fields ListA
Read-onlyIdempotent

List custom fields and their values (for setting on stories).

Inputs: includeDisabled.

documents-createDocuments: CreateB

Create a new document (Markdown format).

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

documents-get-by-idDocuments: Get By IDA
Read-onlyIdempotent

Get a document by ID (returns Markdown).

Inputs: docId (required).

documents-listDocuments: ListA
Read-onlyIdempotent

List all documents.

Inputs: no named parameters.

documents-updateDocuments: UpdateC

Update a document's title or content.

Inputs: docId (required), title, content.

epics-createEpics: CreateB

Create a new Shortcut epic.

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

epics-create-commentEpics: Create CommentB

Add a comment to an epic.

Inputs: text (required), epicPublicId (required), replyToCommentId.

epics-deleteEpics: DeleteA
Destructive

Delete an epic (cannot be undone).

Inputs: epicPublicId (required).

epics-get-by-idEpics: Get By IDB
Read-onlyIdempotent

Get a Shortcut epic by public ID.

Inputs: epicPublicId (required), full.

epics-updateEpics: UpdateA

Update an epic. Only provide fields to update.

Inputs: epicPublicId (required), name, state, labels, +10 more.

iterations-createIterations: CreateC

Create a new Shortcut iteration.

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

iterations-deleteIterations: DeleteA
Destructive

Delete an iteration (cannot be undone).

Inputs: iterationPublicId (required).

iterations-get-activeIterations: Get ActiveA
Read-onlyIdempotent

Get active iterations for current user's teams.

Inputs: teamId.

iterations-get-by-idIterations: Get By IDA
Read-onlyIdempotent

Get a Shortcut iteration by public ID.

Inputs: iterationPublicId (required), full.

iterations-get-storiesIterations: Get StoriesB
Read-onlyIdempotent

Get all stories in an iteration.

Inputs: iterationPublicId (required), includeStoryDescriptions.

iterations-get-upcomingIterations: Get UpcomingA
Read-onlyIdempotent

Get upcoming iterations for current user's teams.

Inputs: teamId.

iterations-updateIterations: UpdateA

Update an iteration. Only provide fields to update.

Inputs: iterationPublicId (required), name, labels, endDate, +4 more.

labels-createLabels: CreateB

Create a new label.

Inputs: name (required), color, description.

labels-get-storiesLabels: Get StoriesA
Read-onlyIdempotent

Get all stories with a specific label.

Inputs: labelPublicId (required).

labels-listLabels: ListA
Read-onlyIdempotent

List all labels in the workspace.

Inputs: includeArchived.

objectives-get-by-idObjectives: Get By IDB
Read-onlyIdempotent

Get a Shortcut objective by public ID.

Inputs: objectivePublicId (required), full.

projects-get-by-idProjects: Get By IDA
Read-onlyIdempotent

Get a Shortcut project by ID.

Inputs: projectPublicId (required).

projects-get-storiesProjects: Get StoriesA
Read-onlyIdempotent

Get all stories in a project.

Inputs: projectPublicId (required).

projects-listProjects: ListA
Read-onlyIdempotent

List all projects in the workspace.

Inputs: includeArchived.

stories-add-relationStories: Add RelationC

Add a relationship between stories.

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

stories-add-subtaskStories: Add SubtaskB

Add existing story as a sub-task.

Inputs: subTaskPublicId (required), parentStoryPublicId (required).

stories-add-taskStories: Add TaskA

Add a task (checklist item) to a story.

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

stories-assign-current-userStories: Assign Current UserB

Assign current user as story owner.

Inputs: storyPublicId (required).

stories-createStories: CreateA

Create a new Shortcut story. Requires name and either team or workflow.

Inputs: name (required), epic, team, type, +4 more.

stories-create-commentStories: Create CommentC

Add a comment to a story.

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

stories-create-subtaskStories: Create SubtaskB

Create a new sub-task story.

Inputs: name (required), parentStoryPublicId (required), description.

stories-get-branch-nameStories: Get Branch NameB
Read-onlyIdempotent

Get a valid git branch name for a story.

Inputs: storyPublicId (required).

stories-get-by-idStories: Get By IDA
Read-onlyIdempotent

Get a Shortcut story by public ID.

Inputs: storyPublicId (required), full.

stories-get-historyStories: Get HistoryA
Read-onlyIdempotent

Get the change history for a Shortcut story.

Inputs: storyPublicId (required).

stories-remove-subtaskStories: Remove SubtaskA
Destructive

Remove sub-task from parent (becomes regular story).

Inputs: subTaskPublicId (required).

stories-unassign-current-userStories: Unassign Current UserB

Remove current user as story owner.

Inputs: storyPublicId (required).

stories-updateStories: UpdateA

Update a Shortcut story. Only provide fields to update.

Inputs: storyPublicId (required), epic, name, type, +13 more.

stories-update-taskStories: Update TaskB

Update a task in a story.

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

stories-upload-fileStories: Upload FileB

Upload a file and attach it to a story.

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

teams-get-by-idTeams: Get By IDA
Read-onlyIdempotent

Get a Shortcut team by ID.

Inputs: teamPublicId (required), full.

teams-listTeams: ListA
Read-onlyIdempotent

List all Shortcut teams.

Inputs: includeArchived.

users-get-currentUsers: Get CurrentA
Read-onlyIdempotent

Get the current user.

Inputs: no named parameters.

users-get-current-teamsUsers: Get Current TeamsA
Read-onlyIdempotent

Get a list of teams where the current user is a member.

Inputs: no named parameters.

users-listUsers: ListB
Read-onlyIdempotent

Get all users.

Inputs: no named parameters.

workflows-get-by-idWorkflows: Get By IDA
Read-onlyIdempotent

Get a Shortcut workflow by ID.

Inputs: workflowPublicId (required), full.

workflows-get-defaultWorkflows: Get DefaultA
Read-onlyIdempotent

Get the default workflow for a team or workspace.

Inputs: teamPublicId.

workflows-listWorkflows: ListA
Read-onlyIdempotent

List all Shortcut workflows.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 56 tools

    Disambiguation5/5

    Each tool targets a distinct entity or action, with clear differentiation even among many story-related tools. No overlapping purposes.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., epics-create, stories-add-relation). No mixing of conventions.

    Tool Count2/5

    With 56 tools, the server is overly large for its domain, exceeding the typical 15-tool sweet spot and causing potential overhead for agents.

    Completeness3/5

    Core CRUD exists for most entities, but notable gaps like missing delete operations for documents and labels hinder full lifecycle coverage.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A Model Context Protocol server that enables interaction with Shortcut (formerly Clubhouse) project management tool, allowing users to view and search projects, stories, epics, and objectives, as well as create new items through natural language.
      5
      -