Shortcut.com MCP Server

# 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 1. Clone this repository: ```bash git clone https://github.com/yourusername/mcp-server-shortcut.git cd mcp-server-shortcut ``` 2. Create a virtual environment and install dependencies: ```bash # 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 ``` 3. 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: ```bash python -m src.server ``` ## Configuring Claude Desktop To use this MCP server with Claude Desktop: 1. Edit the Claude Desktop configuration file: - Mac: `~/Library/Application Support/Claude/claude_desktop_config.json` - Windows: `%APPDATA%\Claude\claude_desktop_config.json` 2. Add the MCP server configuration: ```json { "mcpServers": { "shortcut": { "command": "python", "args": ["-m", "src.server"], "env": { "SHORTCUT_API_TOKEN": "your_token_here" } } } } ``` 3. 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: 1. Add any new API methods to `shortcut_client.py` 2. Define Pydantic models in `utils.py` if needed 3. 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](LICENSE)