Shortcut MCP Server
A Model Context Protocol (MCP) server that provides comprehensive tools for interacting with the Shortcut API and analyzing Loom videos attached to stories. This server helps developers:
- Read and update stories, manage comments, and query project data
- Analyze Loom videos for debugging insights
- Correlate video content with codebase to identify relevant files
- Generate debugging plans based on video analysis
Features
- Story Management: Get, search, and update stories
- Comment System: Add and retrieve story comments
- Project Organization: List projects, epics, and workflows
- File Attachments: Download and analyze file attachments from stories
- Video Analysis: Extract and analyze Loom videos from stories for debugging
- Codebase Correlation: Match video content with relevant source files
- Debugging Assistance: Generate debugging plans from video analysis
- Type Safety: Full TypeScript support with comprehensive type definitions
- Error Handling: Robust error handling with detailed error messages
- Response Size Management: Automatic warnings for large responses (>20k tokens)
Installation
- Clone the repository:
git clone <repository-url>
cd shortcut-mcp
- Install dependencies using pnpm:
pnpm install
- Create the configuration directory and file:
mkdir -p ~/.shortcut_mcp
echo "SHORTCUT_TOKEN=your-api-token-here" > ~/.shortcut_mcp/.env
- Build the project:
pnpm run build
Configuration
The server reads the Shortcut API token from ~/.shortcut_mcp/.env. This file should contain:
SHORTCUT_TOKEN=your-shortcut-api-token
To obtain your Shortcut API token:
- Log in to Shortcut
- Navigate to Settings > API Tokens
- Generate a new token
- Copy the token to your .env file
Usage
Start the MCP server:
./start_mcp.sh
For development mode with hot reload:
./start_mcp.sh dev
For hot reload support that maintains MCP connection:
./start_mcp_with_proxy.sh
# In another terminal, trigger reload with:
./reload_mcp.sh
Available Tools
Story Operations
shortcut_get_story- Get detailed information about a specific storyshortcut_search_stories- Search for stories using Shortcut's query syntaxshortcut_get_project_stories- Get all stories in a specific projectshortcut_get_epic_stories- Get all stories in a specific epicshortcut_update_story- Update story attributes (description, labels, workflow state, etc.)
Comment Operations
shortcut_add_comment- Add a comment to a storyshortcut_get_comments- Retrieve all comments for a story
Organization Tools
shortcut_list_workflows- List all workflows and their statesshortcut_list_projects- List all projects in the workspaceshortcut_list_epics- List all epics in the workspace
File Operations
shortcut_get_story_files- Get all file attachments for a storyshortcut_download_file- Download file content from attachments (text or binary)
Video Analysis Tools
shortcut_get_story_loom_videos- Extract Loom video links from a storyshortcut_analyze_loom_video- Analyze Loom video metadata, transcript, and debugging insightsshortcut_analyze_video_with_codebase- Correlate video content with codebase filesshortcut_debug_video_issue- Deep debugging analysis with action tracking and error detectionshortcut_analyze_video_with_anthropic- (Currently disabled) Visual analysis using Claude Vision
Development
Scripts
pnpm run dev- Run in development mode with hot reloadpnpm run build- Build TypeScript to JavaScriptpnpm run typecheck- Check TypeScript typespnpm run lint- Run ESLintpnpm run format- Format code with Prettierpnpm test- Run unit and integration tests
Project Structure
shortcut-mcp/
├── src/
│ ├── server.ts # Main MCP server implementation
│ ├── shortcutClient.ts # Shortcut API client
│ ├── shortcut-types.ts # TypeScript type definitions
│ ├── loomClient.ts # Loom API integration
│ ├── loomDetector.ts # Loom URL detection utilities
│ ├── videoAnalysis.ts # Core video analysis service
│ ├── videoCodeAnalyzer.ts # Codebase correlation analysis
│ ├── enhancedVideoAnalyzer.ts # Deep debugging analysis
│ ├── audioAnalyzer.ts # Audio transcript analysis
│ ├── visualAnalyzer.ts # Visual element detection
│ ├── debuggingAssistant.ts # Debugging plan generation
│ ├── proxy.ts # Hot reload proxy server
│ └── mimeTypes.ts # File type utilities
├── tests/ # Test files
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── dist/ # Compiled JavaScript (generated)
├── start_mcp.sh # Standard server startup script
├── start_mcp_with_proxy.sh # Hot reload startup script
├── reload_mcp.sh # Trigger hot reload
├── package.json # Project configuration
└── tsconfig.json # TypeScript configuration
Error Handling
The server provides detailed error messages for common issues:
- Missing or invalid API token
- API request failures
- Invalid story/project/epic IDs
- Network connectivity issues
License
ISC