MCP Server Shortcut

🚀 Shortcut.com MCP Server

A project implementing the Shortcut.com Model Context Protocol (MCP) server for accessing and searching Shortcut.com tickets.

🚀 Quick Start

This project implements an MCP server that interacts with the Shortcut.com ticketing management system. Through this integration, Claude and other MCP-compatible 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.

✨ Features

Resources

• shortcut://stories - Access the story list.
• shortcut://story/{story_id} - Access a specific story.

Tools

• list_stories - List stories with optional filtering.
• search_stories - Search for stories using a text query.
• 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 bug report template.
• create_feature_request - Generate a feature request template.

📦 Installation

Prerequisites

• Python 3.10+
• Shortcut.com API token

Steps

1. Clone this repository:

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

2. Create a virtual environment and install dependencies:

# Using uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh  # 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

3. Create a .env file in the project root directory and add your Shortcut API token:

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

💻 Usage Examples

Running the Server

Use the following command to start the MCP server:

python -m src.server

Configuring Claude Desktop

To use this MCP server with Claude Desktop:

1. Edit Claude Desktop's configuration file:

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MCP server configuration:

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

3. Restart Claude Desktop.

📚 Documentation

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 variable file

Contributors

• [Your Name] - Initial implementation

License

[Specify the license here, e.g., MIT or Apache]

Contact

• Email: [your.email@example.com]
• GitHub: @yourusername

This document describes how to set up and run the Shortcut.com MCP server and integrate it with Claude Desktop.