What is Shortcut Mcp

shortcut-mcp is a Model Context Protocol (MCP) server designed for interacting with Shortcut (formerly known as Clubhouse), enabling users to manage projects, stories, epics, and objectives in a structured manner.

Use cases

Use cases for shortcut-mcp include integrating with project management tools, automating story creation, and providing a safe interface for accessing and managing project data without the risk of data loss.

How to use

To use shortcut-mcp, install Python with asdf, set up a virtual environment, install dependencies, configure your environment with your Shortcut API token, and run the server using the command ‘python -m shortcut_mcp’.

Key features

Key features of shortcut-mcp include viewing projects, stories, epics, and objectives, searching through stories, creating new stories, epics, and objectives, and ensuring safe operations with read-only access and no data modification or deletion.

Where to use

shortcut-mcp can be used in project management, software development, and team collaboration environments where interaction with Shortcut is required.

Shortcut MCP Server

[!WARNING]
This is a WIP server and might not work as intended.

A Model Context Protocol (MCP) server for interacting with Shortcut (formerly Clubhouse).

Features

• View projects, stories, epics, and objectives
• Search through stories
• Create new stories, epics, and objectives
• Safe operations only (no updates or deletions)

Setup

1. Install Python with asdf:

asdf install

2. Create virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .  # Install package in editable mode

3. Set up your environment:

cp .env.example .env
# Edit .env and add your Shortcut API token

4. Run the server:

python -m shortcut_mcp

Project Structure

shortcut-mcp/
├── src/
│   └── shortcut_mcp/      # Main package directory
│       ├── __init__.py    # Package initialization
│       ├── __main__.py    # Entry point
│       └── server.py      # Server implementation
├── pyproject.toml         # Project configuration
├── .tool-versions         # ASDF version configuration
├── .pylintrc             # Pylint configuration
└── README.md

Using with Claude Desktop

Add this to your Claude Desktop config:

On MacOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "shortcut": {
      "command": "python",
      "args": [
        "-m",
        "shortcut_mcp"
      ],
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here"
      }
    }
  }
}

On Windows (%AppData%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "shortcut": {
      "command": "python",
      "args": [
        "-m",
        "shortcut_mcp"
      ],
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here"
      }
    }
  }
}

Testing

You can test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector python -m shortcut_mcp

Safety Features

This server implements read-only operations with safe creation capabilities:

• Only allows GET (read) and POST (create) operations
• No modification or deletion of existing data
• All operations are attributed to the API token owner

Development

Python Version Management

This project uses asdf for Python version management. The required Python version is specified in .tool-versions.

# Install Python with asdf
asdf install python

# The correct version will be automatically selected based on .tool-versions

Code Quality

We use pylint for code quality checks. Run it with:

pylint src/shortcut_mcp

The configuration for pylint is in .pylintrc.