Skip to main content
Glama
currentspace

Shortcut MCP Server

by currentspace
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Remote

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