Shortcut MCP
A Model Context Protocol (MCP) server for interacting with Shortcut (formerly Clubhouse)
Installation
npx shortcut-mcpAsk AI about Shortcut MCP
Powered by Claude Β· Grounded in docs
I know everything about Shortcut MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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_idandteam_nameparameters - New Tool: Use the
list-teamstool 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
.envfile is included in.gitignoreto 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 stateslist-my-stories- View stories assigned to youlist-stories-by-state-name- View stories in a specific stateadvanced-search-stories- Find stories with multiple filterslist-teams- View all teams in your Shortcut workspacesearch-stories- Find stories by keywordslist-archived-stories- View archived storieslist-my-archived-stories- View your archived stories
Note: Projects have been deprecated by Shortcut. The
list-projectstool will now inform you to use teams instead. When creating or updating stories, please useteam_idorteam_nameparameters 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
- Clone the repository:
git clone https://github.com/idyll/shortcut-mcp.git
cd shortcut-mcp
- Install Python with asdf:
asdf install
- 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
- Set up your environment:
cp .env.example .env
# Edit .env and add your Shortcut API token
- 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 dateupdated_after/updated_before: Filter by last update date
- Archived Stories: All search tools exclude archived stories by default
- Use
include_archived: trueparameter to include archived stories - Dedicated tools for working with archived stories:
list-archived-storiesandlist-my-archived-stories
- Use
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.
