shortcut-mcp 0.2.3

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

Shortcut MCP Server

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

Acknowledgments

This project is based on the original work by Antonio Lorusso. Mark Madsen's fork extends the original implementation with additional features including advanced search capabilities, improved CLI tools, and enhanced user experience.

Features

• View stories, epics, objectives, and teams
• Search through stories with advanced filtering options
• Create new stories, epics, and objectives
• Safe operations only (no updates or deletions)
• Archived stories management (excluded by default, with option to include)

What's New in 0.2.3

• Project Deprecation: Updated to use teams instead of projects, as projects have been deprecated by Shortcut
• Improved ID Handling: Better support for both numeric IDs and UUID strings for teams and epics
• Enhanced Team Support: Improved team assignment when creating and updating stories

What's New in 0.2.2

• Enhanced Search Functionality: Improved search capabilities with support for Shortcut's native query syntax
• Advanced Query Operators: Support for operators like type:, state:, owner:, label:, and more
• Better Error Handling: More detailed error messages and improved fallback mechanisms
• Robust Story ID Handling: Better handling of non-numeric characters in story IDs

What's New in 0.2.1

• Team Management: Added support for assigning teams to stories using team_id and team_name parameters
• New Tool: Use the list-teams tool to see all available teams in your Shortcut workspace
• Improved Reliability: Better handling of parameters and error conditions
• Enhanced Epic Support: Improved support for linking stories to epics

Installation

Standard Installation

pip install shortcut-mcp

MacOS Installation with Homebrew and pipx

For MacOS users, we recommend using Homebrew and pipx for a cleaner installation:

# Install pipx if you don't have it already
brew install pipx
pipx ensurepath

# Install shortcut-mcp
pipx install shortcut-mcp

This method installs shortcut-mcp in an isolated environment, preventing dependency conflicts with other Python packages.

Upgrading

To upgrade to the latest version:

# Standard upgrade
pip install --upgrade shortcut-mcp

# If installed with pipx
pipx upgrade shortcut-mcp

Quick Start

1. Set up with Claude Desktop

# Install and set up in one step
shortcut-mcp setup

You'll be prompted for your Shortcut API token, which you can find in your Shortcut settings.

Security Note: Your API token grants access to your Shortcut account. Never share it publicly or commit it to version control. The .env file is included in .gitignore to help prevent accidental exposure.

2. Using in Claude

After setup, you can now use the Shortcut tools directly in Claude Desktop. Try these commands:

• list-workflows - See all workflow states
• list-my-stories - View stories assigned to you
• list-stories-by-state-name - View stories in a specific state
• advanced-search-stories - Find stories with multiple filters
• list-teams - View all teams in your Shortcut workspace
• search-stories - Find stories by keywords
• list-archived-stories - View archived stories
• list-my-archived-stories - View your archived stories

Note: Projects have been deprecated by Shortcut. The list-projects tool will now inform you to use teams instead. When creating or updating stories, please use team_id or team_name parameters instead of project-related parameters.

Manual Usage

If you want to run the server manually:

# Set your API token
export SHORTCUT_API_TOKEN=your_token_here

# Start the server
shortcut-mcp start

Development Setup

1. Clone the repository:

git clone https://github.com/idyll/shortcut-mcp.git
cd shortcut-mcp

2. Install Python with asdf:

asdf install

3. 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

4. Set up your environment:

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

5. 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
│       ├── cli.py         # CLI implementation
│       └── server.py      # Server implementation
├── pyproject.toml         # Project configuration
├── .tool-versions         # ASDF version configuration
└── README.md

Using with Claude Desktop

The shortcut-mcp setup command will automatically configure Claude Desktop for you. If you want to do it manually, add this to your Claude Desktop config:

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

{
  "mcpServers": {
    "shortcut": {
      "command": "shortcut-mcp",
      "args": ["start"],
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here"
      }
    }
  }
}

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

{
  "mcpServers": {
    "shortcut": {
      "command": "shortcut-mcp",
      "args": ["start"],
      "env": {
        "SHORTCUT_API_TOKEN": "your_token_here"
      }
    }
  }
}

Testing

You can test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector shortcut-mcp start

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

Building and Publishing

Once your code is ready:

# Install build tools
pip install build twine

# Build the package
python -m build

# Upload to PyPI
python -m twine upload dist/*

Advanced Search Features

The Shortcut MCP server provides powerful search capabilities through the advanced-search-stories tool:

Search Parameters

• Owner vs. Requestor: Distinguish between the person assigned to a story (owner) and the person who requested it
• Workflow State: Filter by specific workflow states like "In Development" or "Ready for Review"
• Time-based Filtering: Find stories based on when they were created or updated
  • created_after / created_before: Filter by creation date
  • updated_after / updated_before: Filter by last update date
• Archived Stories: All search tools exclude archived stories by default
  • Use include_archived: true parameter to include archived stories
  • Dedicated tools for working with archived stories: list-archived-stories and list-my-archived-stories

Example Queries

In Claude, you can use commands like:

• "Find stories requested by John but owned by Sarah"
• "Show me stories in the Ready for Review state created in the last month"
• "Search for stories updated after 2023-01-01 in the In Development state"
• "List archived stories in the Done state"
• "Show my archived stories from the last quarter"

This makes it easy to find exactly the stories you're looking for, even in large projects with many tickets.