Overview

The MCP Server for Shortcut exposes your Shortcut (formerly Clubhouse) workspace as an MCP (Model Context Protocol) service so IDEs and AI tools can read and modify projects, stories, labels, epics, iterations, and more. It implements a set of “tools” that map common Shortcut operations (search stories, create comments, upload attachments, etc.) into MCP actions, letting editors and assistants integrate with your task data without directly calling the Shortcut REST API.

This server supports both hosted and local deployments. The hosted endpoint handles OAuth for you, making it easy to connect clients such as Cursor or VS Code. If your environment doesn’t support HTTP-based MCP servers, you can run a stdio-based local server for IDEs like Windsurf, Zed, or Claude Code.

Features

Surface Shortcut workspaces as MCP tools for quick lookup, creation, and modification of stories, epics, labels, custom fields, iterations, and teams.
OAuth-based authentication for hosted server — no API tokens required for most clients.
HTTP and stdio transport modes to support a variety of IDEs and MCP-compatible tools.
File upload and story attachment support (upload an asset and link it to a story).
Branch-name suggestion tool to generate recommended branch names based on workspace and story metadata.
Team-aware iteration and iteration search tools to find active/upcoming iterations for the authenticated user.

Installation / Configuration

Add the MCP server to your environment by configuring the client’s MCP servers list.

Cursor / Local mcp.json

{
  "mcpServers": {
    "shortcut": {
      "url": "https://mcp.shortcut.com/mcp"
    }
  }
}

VS Code (settings.json MCP servers block)

{
  "servers": {
    "shortcut-mcp": {
      "type": "http",
      "url": "https://mcp.shortcut.com/mcp"
    }
  }
}

Claude Desktop

Download the .mcpb package from the repository releases (or raw file).
Double-click the package or drag it onto the Claude Desktop client to install.

Local / stdio server

If your IDE requires a stdio MCP server, follow the repository’s Local Server Setup guide (docs/local-server.md) to run the server locally and configure the client to launch it over stdio instead of HTTP.

Authentication

Hosted server: OAuth flow is handled by the server — you’ll be prompted to authorize on first use.
Local server: You may need to supply a Shortcut API token or configure OAuth locally depending on the server setup instructions.

Available Tools

The server exposes grouped tools that mirror Shortcut concepts. Below are representative examples; see the repository for the full tool list.

Stories

Tool	Purpose
stories-get-by-id	Fetch a story by ID
stories-search	Search and filter stories
stories-create	Create a new story
stories-update	Update an existing story
stories-create-comment	Add a comment to a story
stories-upload-file	Upload and attach a file

Projects, Labels & Custom Fields

Tool	Purpose
projects-list / projects-get-by-id	List and fetch projects
labels-list / labels-get-stories	Manage labels and find stories by label
custom-fields-list	Enumerate custom fields and values

Epics, Iterations & Objectives

Tool	Purpose
epics-get-by-id / epics-search	Work with epics
iterations-get-active / iterations-create	Query and create iterations
objectives-search	Find objectives

Teams & Utilities

Tool	Purpose
teams-list / teams-get-by-id	Team information
stories-get-branch-name	Suggested branch names based on story/workspace settings

For the exhaustive list, check the repository’s tools directory (src/tools) or the README in the project.

Use Cases

Create a branch for a story

Use stories-get-by-id to retrieve the story title and metadata, then stories-get-branch-name to compute a recommended git branch name used by your local tooling.

Auto-create stories from PR templates or chat prompts

An assistant can call stories-create via MCP to add a new story with description, labels, and assignee from a developer’s prompt or a pull request title.

Sync statuses between code review and project board

On CI or from an IDE assistant, query stories-search for linked stories and call stories-update to change workflow state after tests or reviews complete.

Bulk label or custom-field updates

Use labels-list and custom-fields-list to enumerate options, then iterate stories-search results and call stories-update to apply consistent metadata across multiple stories.

Attach files (screenshots, logs) to stories

Upload a file with stories-upload-file and then link it to the target story to centralize debugging artifacts.

Getting Help and Contributing

Hosted usage and quick-start: use the client-specific docs (Cursor, VS Code, Claude) to connect.
Local setup and development: see docs/local-server.md and docs/developer.md in the repository.
Contributions are welcome — open issues and PRs on the GitHub repo: https://github.com/useshortcut/mcp-server-shortcut

This MCP server is intended for developers integrating Shortcut data into IDEs and AI assistants, enabling in-editor task management, automation, and richer context for code-related workflows.

MCP Server: Access Shortcut Projects and Stories