Shortcut

🚀 Shortcut.com MCP Server

An implementation of a Model Context Protocol (MCP) server for accessing and searching the Shortcut.com ticketing system.

🚀 Quick Start

This project implements an MCP server that interacts with Claude and other AI assistants supporting the MCP protocol, allowing these AI assistants to interact with Shortcut.com's ticketing management system. Through 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.

✨ 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:

   # Use 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
   
   # Use 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

Run the Server

Use the following command to start the MCP server:

python -m src.server

Configure 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 - The main file of the MCP server.
  • client.py - Example client code for interacting with the MCP server.
  • config.py - Configuration settings and environment variables.
  • requirements.txt - Python dependencies required for the project.

Development

To add new features to this project, follow these steps:

1. Clone the repository and install dependencies in your local environment.
2. Modify the code to add the desired features.
3. Test the changes to ensure all existing features continue to work properly.
4. Commit the changes and create a pull request.

Contribution

We welcome contributions from the community! If you find any issues or have any improvement suggestions, please submit an issue or a pull request. Please refer to our Contribution Guidelines for how to participate.

📄 License

This project is licensed under the MIT License.