README.md

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.