Shortcut.com MCP Server

An implementation of a Model Context Protocol (MCP) server for accessing and searching tickets on Shortcut.com.

Overview

This project implements an MCP server that allows Claude and other MCP-compatible AI assistants to interact with Shortcut.com's ticket management system. With this integration, AI assistants can:

List and search for stories (tickets) in Shortcut
Get detailed information about specific stories
Create new stories
Update existing stories
Add comments to stories
Retrieve workflow states and projects

Prerequisites

Python 3.10+
Shortcut.com API token

Installation

Clone this repository:

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

Create a virtual environment and install dependencies:

# Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh  # For Mac/Linux
uv venv
source .venv/bin/activate  # On Mac/Linux or .venv\Scripts\activate on Windows
uv pip install -r requirements.txt

# Using pip
python -m venv venv
source venv/bin/activate  # On Mac/Linux or venv\Scripts\activate on Windows
pip install -r requirements.txt

Create a .env file in the project root directory with your Shortcut API token:

SHORTCUT_API_TOKEN=your_token_here
SERVER_PORT=5000
SERVER_HOST=0.0.0.0
DEBUG_MODE=True

Running the Server

Start the MCP server using:

python -m src.server

Configuring Claude Desktop

To use this MCP server with Claude Desktop:

Edit the Claude Desktop configuration file:
- Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the MCP server configuration:

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

Restart Claude Desktop.

Available MCP Capabilities

Resources

shortcut://stories - Access a list of stories
shortcut://story/{story_id} - Access a specific story

Tools

list_stories - List stories with optional filtering
search_stories - Search for stories using text queries
get_story_details - Get detailed information about a specific story
create_story - Create a new story
update_story - Update an existing story
add_comment - Add a comment to a story
list_workflow_states - List all workflow states
list_projects - List all projects

Prompts

create_bug_report - Generate a template for bug reports
create_feature_request - Generate a template for feature requests

Project Structure

src/ - Source code directory
- server.py - Main MCP server implementation
- config.py - Configuration management
- shortcut_client.py - Client for the Shortcut API
- utils.py - Utility functions and data models
requirements.txt - Project dependencies
.env - Environment variables (not tracked in git)

Development

Adding New Capabilities

To add a new capability to the MCP server:

Add any new API methods to shortcut_client.py
Define Pydantic models in utils.py if needed
Implement the MCP functionality using decorators in server.py:
- Use @mcp.resource() for read-only resources
- Use @mcp.tool() for actions that can modify data
- Use @mcp.prompt() for generating templates or structured text

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License