YouTrack MCP TypeScript Server

A Model Context Protocol (MCP) server for YouTrack integration, providing a standardized interface for LLMs to interact with YouTrack’s issue tracking, agile management, and knowledge base features.

Features

• Issue Management

  • Create, read, update, delete issues
  • Add comments and attachments
  • Search issues with advanced filtering
  • Track issue time and estimation

• Agile & Sprint Management

  • Create and manage sprints
  • Assign issues to sprints
  • Track sprint progress

• State Management & Workflows

  • Transition issues through states
  • Start working on issues with automatic assignment
  • Complete issues with proper resolution

• Knowledge Base Integration

  • Create and manage articles
  • Link issues to knowledge base articles
  • Search knowledge base content

• Project Management

  • List and filter projects
  • Get project details and customization options

Installation

# Clone the repository
git clone https://github.com/itsalfredakku/youtrack-mcp.git
cd youtrack-mcp-ts

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Copy the example environment file and configure it with your YouTrack instance details:

cp .env.example .env

Edit the .env file with your specific configuration:

# YouTrack instance URL (without trailing slash)
YOUTRACK_URL=https://your-instance.youtrack.cloud

# YouTrack permanent token
# Generate from: Profile > Account Security > Tokens
YOUTRACK_TOKEN=your-permanent-token-here

# Optional: Default project ID
PROJECT_ID=PROJECT-1

# Optional: Enable webhooks (true/false)
ENABLE_WEBHOOKS=false

# Optional: Webhook server port (default: 3000)
WEBHOOK_PORT=3000

# Optional: Webhook secret for signature verification
WEBHOOK_SECRET=your-webhook-secret

# Optional: Log level (error, warn, info, debug)
LOG_LEVEL=info

# Optional: Cache TTL in milliseconds (default: 300000 = 5 minutes)
CACHE_TTL=300000

# Optional: Enable cache (true/false, default: true)
CACHE_ENABLED=true

Usage

Starting the Server

# Start the MCP server
npm start

# Start in development mode with auto-reload
npm run dev

Interacting with the Server

The YouTrack MCP server exposes tools following the Model Context Protocol. LLM applications can discover and use these tools to interact with YouTrack.

Example: Creating an Issue

{
  "tool": "create_issue",
  "params": {
    "projectId": "PROJECT-1",
    "summary": "Implement new feature",
    "description": "We need to implement the new feature as described in the specs.",
    "type": "Task",
    "priority": "Normal"
  }
}