Docs & Usage Guide

YouTrack MCP

A Model Context Protocol (MCP) server that provides access to YouTrack functionality.

🚀 Quick Reference - Common Operations

🎯 State Transitions (Most Common)

# ✅ PROVEN WORKING FORMAT - Use simple strings
update_issue_state("DEMO-123", "In Progress")
update_issue_state("PROJECT-456", "Fixed")
update_issue_state("TASK-789", "Closed")

# ❌ DON'T USE - Complex objects fail
# update_custom_fields(issue_id, {"State": {"name": "In Progress"}})  # FAILS
# update_custom_fields(issue_id, {"State": {"id": "154-2"}})         # FAILS

🚨 Priority Updates (Very Common)

# ✅ PROVEN WORKING FORMAT - Use simple strings
update_issue_priority("DEMO-123", "Critical")
update_issue_priority("PROJECT-456", "Major") 
update_issue_priority("TASK-789", "Normal")

# ❌ DON'T USE - Complex objects fail
# update_custom_fields(issue_id, {"Priority": {"name": "Critical"}})  # FAILS
# update_custom_fields(issue_id, {"Priority": {"id": "152-1"}})       # FAILS

👤 Assignment Updates (Common)

# ✅ PROVEN WORKING FORMAT - Use login names
update_issue_assignee("DEMO-123", "admin")
update_issue_assignee("PROJECT-456", "john.doe")
update_issue_assignee("TASK-789", "jane.smith")

# ❌ DON'T USE - Complex objects fail
# update_custom_fields(issue_id, {"Assignee": {"login": "admin"}})    # FAILS

🏷️ Type Updates (Common)

# ✅ PROVEN WORKING FORMAT - Use simple strings
update_issue_type("DEMO-123", "Bug")
update_issue_type("PROJECT-456", "Feature")
update_issue_type("TASK-789", "Task")

# ❌ DON'T USE - Complex objects fail
# update_custom_fields(issue_id, {"Type": {"name": "Bug"}})          # FAILS

⏱️ Time Estimation (Common)

# ✅ PROVEN WORKING FORMAT - Use simple time strings
update_issue_estimation("DEMO-123", "4h")     # 4 hours
update_issue_estimation("PROJECT-456", "2d")  # 2 days
update_issue_estimation("TASK-789", "30m")    # 30 minutes
update_issue_estimation("TASK-790", "1w")     # 1 week
update_issue_estimation("TASK-791", "3d 5h")  # 3 days 5 hours

# ❌ DON'T USE - ISO duration or complex formats fail
# update_custom_fields(issue_id, {"Estimation": "PT4H"})             # FAILS

⚡ Complete Issue Workflows

# 🎯 Complete Triage Workflow
update_issue_type("DEMO-123", "Bug")           # Classify as bug
update_issue_priority("DEMO-123", "Critical")  # Set priority  
update_issue_assignee("DEMO-123", "admin")     # Assign to admin
update_issue_estimation("DEMO-123", "4h")      # Estimate 4 hours
update_issue_state("DEMO-123", "In Progress")  # Start work
add_comment("DEMO-123", "Critical bug triaged and assigned")

# 🚀 Feature Development Workflow  
update_issue_type("PROJ-456", "Feature")       # Classify as feature
update_issue_priority("PROJ-456", "Normal")    # Standard priority
update_issue_assignee("PROJ-456", "jane.doe")  # Assign to developer
update_issue_estimation("PROJ-456", "2d")      # Estimate 2 days
add_comment("PROJ-456", "Feature ready for development")

# ✅ Task Completion Workflow
update_issue_state("TASK-789", "Fixed")        # Mark as fixed
add_comment("TASK-789", "Implementation completed and tested")

# 📊 Quick Updates (Most Common)
update_issue_state("DEMO-123", "In Progress")       # Start work
update_issue_priority("DEMO-123", "Critical")       # Escalate
update_issue_assignee("DEMO-123", "admin")          # Reassign
update_issue_type("DEMO-123", "Bug")                # Reclassify
update_issue_estimation("DEMO-123", "6h")           # Re-estimate

📝 Other Custom Fields

# ✅ Working formats for different field types:

# Priority (enum field)
update_custom_fields("DEMO-123", {"Priority": "Critical"})

# Assignee (user field) 
update_custom_fields("DEMO-123", {"Assignee": "admin"})

# Estimation (period field)
update_custom_fields("DEMO-123", {"Estimation": "4h"})

# Type (enum field)
update_custom_fields("DEMO-123", {"Type": "Bug"})

# Multiple fields at once
update_custom_fields("DEMO-123", {
    "Priority": "Critical",
    "Assignee": "admin", 
    "Type": "Bug"
})

🔍 Finding Issues

# Search by text
search_issues("bug in login")

# Search by project
get_project_issues("DEMO")

# Get specific issue
get_issue("DEMO-123")

📋 Creating Issues

create_issue(
    project_id="DEMO",
    summary="Bug in login system",
    description="Users cannot log in with special characters"
)

🔗 Linking Issues

# Create dependency
add_dependency("DEMO-123", "DEMO-124")

# Create relates link
add_relates_link("DEMO-123", "DEMO-125")

💬 Comments

add_comment("DEMO-123", "Fixed the login bug")
get_issue_comments("DEMO-123")

Installation

This project provides a Model Context Protocol (MCP) server for YouTrack, enabling seamless integration with Claude Desktop and other MCP clients.

Quick Start

Using Docker (Recommended)

Choose from multiple registries:

Docker Hub (Primary)

# Use the latest stable release
docker run --rm \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  tonyzorin/youtrack-mcp:latest

# Or use the latest development build
docker run --rm \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  tonyzorin/youtrack-mcp:1.1.2_wip

GitHub Container Registry (New)

# Use the latest stable release
docker run --rm \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  ghcr.io/tonyzorin/youtrack-mcp:latest

# Or use the latest development build
docker run --rm \
  -e YOUTRACK_URL="https://your-instance.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  ghcr.io/tonyzorin/youtrack-mcp:1.1.2_wip

Available Docker Tags

Both registries provide identical tags:

latest - Latest stable release (currently 1.1.2)
1.1.2 - Specific version tags
1.1.2_wip - Work-in-progress builds from main branch
pr-<number> - Pull request builds for testing

Note: Images are now published to both Docker Hub and GitHub Container Registry simultaneously.

Using npm Package

Choose from multiple registries:

npmjs.org (Primary)

# Install globally
npm install -g youtrack-mcp-tonyzorin

# Or use with npx (no installation required)
npx youtrack-mcp-tonyzorin

GitHub Packages (New)

# Configure GitHub registry
npm config set @tonyzorin:registry https://npm.pkg.github.com

# Install globally
npm install -g @tonyzorin/youtrack-mcp

# Or use with npx
npx @tonyzorin/youtrack-mcp

Features

Issue Management: Create, read, update, and delete YouTrack issues
Project Management: Access project information and custom fields
Search Capabilities: Advanced search with filters and custom fields
User Management: Retrieve user information and permissions
Attachment Support: Download and process issue attachments (up to 10MB)
Multi-Platform Support: ARM64/Apple Silicon and AMD64 architecture support
Comprehensive API: Full YouTrack REST API integration

Development

This project maintains high code quality with comprehensive testing:

Test Coverage: 41% (continuously improving)
CI/CD Pipeline: Automated testing and Docker builds
Quality Assurance: Automated testing on every commit

For development instructions, see the Automation Scripts Guide and Release Process.

Configuration

Environment Variables

YOUTRACK_URL: Your YouTrack instance URL
YOUTRACK_API_TOKEN: Your YouTrack API token
YOUTRACK_VERIFY_SSL: SSL verification (default: true)

Example Configuration

export YOUTRACK_URL="https://prodcamp.youtrack.cloud/"
export YOUTRACK_API_TOKEN="perm-YWRtaW4=.NDMtMg==.JgbpvnDbEu7RSWwAJT6Ab3iXgQyPwu"
export YOUTRACK_VERIFY_SSL="true"

Documentation

Support

For issues and questions:

Check the Issues page
Review the documentation
Submit a new issue with detailed information
Contact directly: t.me/tonyzorin

Latest update: Comprehensive custom fields management with 567 test coverage and clean project organization.

Version 1.11.1 Released

🎉 MAJOR FEATURE - Custom Fields Management Support

✅ Complete custom fields CRUD operations (create, read, update, delete)
✅ Field validation against project schema (all field types supported)
✅ Batch update capabilities for performance
✅ Comprehensive error handling with detailed messages
✅ 567 tests (+68 new tests) with extensive coverage
✅ Clean project organization with automations/ directory

YouTrack