Submit
currentspace

Shortcut MCP Server

Community currentspace
Updated

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

  1. Clone the repository:
git clone <repository-url>
cd shortcut-mcp
  1. Install dependencies using pnpm:
pnpm install
  1. Create the configuration directory and file:
mkdir -p ~/.shortcut_mcp
echo "SHORTCUT_TOKEN=your-api-token-here" > ~/.shortcut_mcp/.env
  1. 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:

  1. Log in to Shortcut
  2. Navigate to Settings > API Tokens
  3. Generate a new token
  4. 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

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

MCP Server · Populars

MCP Server · New