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)

Related MCP server: autonomous-frontend-browser-tools

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 story
shortcut_search_stories - Search for stories using Shortcut's query syntax
shortcut_get_project_stories - Get all stories in a specific project
shortcut_get_epic_stories - Get all stories in a specific epic
shortcut_update_story - Update story attributes (description, labels, workflow state, etc.)

Comment Operations

shortcut_add_comment - Add a comment to a story
shortcut_get_comments - Retrieve all comments for a story

Organization Tools

shortcut_list_workflows - List all workflows and their states
shortcut_list_projects - List all projects in the workspace
shortcut_list_epics - List all epics in the workspace

File Operations

shortcut_get_story_files - Get all file attachments for a story
shortcut_download_file - Download file content from attachments (text or binary)

Video Analysis Tools

shortcut_get_story_loom_videos - Extract Loom video links from a story
shortcut_analyze_loom_video - Analyze Loom video metadata, transcript, and debugging insights
shortcut_analyze_video_with_codebase - Correlate video content with codebase files
shortcut_debug_video_issue - Deep debugging analysis with action tracking and error detection
shortcut_analyze_video_with_anthropic - (Currently disabled) Visual analysis using Claude Vision

Development

Scripts

pnpm run dev - Run in development mode with hot reload
pnpm run build - Build TypeScript to JavaScript
pnpm run typecheck - Check TypeScript types
pnpm run lint - Run ESLint
pnpm run format - Format code with Prettier
pnpm 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