Skip to main content
Glama
tonyzorin

YouTrack MCP

by tonyzorin
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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")

📎 Attachments

# Get raw issue data with attachments
get_issue_raw("DEMO-123")

# Download attachment content as base64
get_attachment_content("DEMO-123", "1-456")

# Delete an attachment (requires permissions)
delete_attachment("DEMO-123", "1-456")

Related MCP server: YouTrack MCP Server

Installation

Docker Build and Push

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, process, and delete 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)

  • DISABLED_TOOLS: Comma-separated list of tools to disable (denylist mode)

  • ENABLED_TOOLS: Comma-separated list of tools to enable (allowlist mode)

Tool Filtering

You can reduce context pollution and token usage by filtering which tools are available:

Denylist Mode - Disable specific tools:

export DISABLED_TOOLS="create_issue,update_issue,delete_page"

Allowlist Mode - Enable only specific tools (disables all others):

export ENABLED_TOOLS="get_issue,search_issues,get_projects"

Notes:

  • Tool names are case-insensitive (Get_Issue = get_issue)

  • Hyphens and underscores are equivalent (get-issue = get_issue)

  • If ENABLED_TOOLS is set, it takes precedence over DISABLED_TOOLS

  • Invalid tool names generate warnings but don't cause errors

  • Filtering happens at startup for maximum efficiency

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:

  1. Check the Issues page

  2. Review the documentation

  3. Submit a new issue with detailed information

  4. 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

This server cannot be installed

A
license - permissive license
-
quality - not tested
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
<1hResponse time
0dRelease cycle
16Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tonyzorin/youtrack-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server