YouTrack MCP Server

A comprehensive Model Context Protocol (MCP) server for YouTrack integration, providing extensive tools for issue tracking, project management, workflow automation, and team collaboration.

Features

🎯 Issue Management

• CRUD Operations: Create, read, update, and delete issues
• Advanced Search: Search issues with complex filters and queries
• Bulk Operations: Update multiple issues at once
• Issue Linking: Manage relationships between issues
• Comments & Attachments: Full support for issue discussions and file attachments
• Work Items: Track time and work logs

📊 Project Management

• Project Operations: List, create, and manage projects
• Custom Fields: Define and manage custom field schemas
• Versions & Milestones: Track releases and project milestones
• Components: Organize issues by components/modules

👥 User & Team Management

• User Operations: List users, groups, and permissions
• Team Collaboration: Manage team assignments and roles
• Notifications: Handle user notifications and subscriptions

🔄 Workflow & Automation

• Workflow States: Manage issue states and transitions
• Custom Workflows: Define and execute custom workflows
• Automation Rules: Set up automated actions and triggers

📈 Analytics & Reporting

• Reports: Generate various project and issue reports
• Statistics: Get project statistics and metrics
• Time Tracking: Comprehensive time tracking and reporting

🏃‍♂️ Agile Features

• Agile Boards: Manage Kanban and Scrum boards
• Sprints: Create and manage sprint cycles
• Burndown Charts: Track progress with visual charts

Installation

Prerequisites

• Node.js 18.0.0 or higher
• YouTrack instance (Cloud or On-Premise)
• YouTrack API token or credentials

🚀 Lightweight Installation Options (Avoid Heavy node_modules)

Option 1: npx (Zero Installation - Recommended)

# Run directly without installing anything locally
npx youtrack-mcp

# Test the installation
npx youtrack-mcp --help

# With environment variables
YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud \
YOUTRACK_TOKEN=your-token \
npx youtrack-mcp

Option 2: Global Installation (Install Once, Use Everywhere)

# Install globally from npm (only ~2MB)
npm install -g youtrack-mcp

# Test the installation
youtrack-mcp --help

# Run with environment variables
YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud \
YOUTRACK_TOKEN=your-token \
youtrack-mcp

Option 3: Using pnpm (70% less disk usage)

# Install pnpm globally (one time setup)
npm install -g pnpm

# Clone and install with pnpm
git clone https://github.com/youtrack-mcp/youtrack-mcp.git
cd youtrack-mcp
pnpm install
pnpm run build

Option 4: Docker Container (Zero local dependencies)

docker run -d --name youtrack-mcp \
  -e YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud \
  -e YOUTRACK_TOKEN=your-token \
  ghcr.io/youtrack-mcp/youtrack-mcp:latest

Traditional Installation (Heavy node_modules)

git clone https://github.com/youtrack-mcp/youtrack-mcp.git
cd youtrack-mcp
npm install
npm run build

Claude Desktop Integration

Add to your claude_desktop_config.json: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 1: npx (Zero Installation - Recommended)

{
  "mcpServers": {
    "youtrack": {
      "command": "npx",
      "args": ["youtrack-mcp"],
      "env": {
        "YOUTRACK_BASE_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "your-permanent-token"
      }
    }
  }
}

Option 2: Global Installation

{
  "mcpServers": {
    "youtrack": {
      "command": "youtrack-mcp",
      "env": {
        "YOUTRACK_BASE_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "your-permanent-token"
      }
    }
  }
}

Option 3: Local Development Build

{
  "mcpServers": {
    "youtrack": {
      "command": "node",
      "args": ["/path/to/youtrack-mcp/build/index.js"],
      "env": {
        "YOUTRACK_BASE_URL": "https://your-instance.youtrack.cloud",
        "YOUTRACK_TOKEN": "your-permanent-token"
      }
    }
  }
}

Option 4: Docker Container

{
  "mcpServers": {
    "youtrack": {
      "command": "docker",
      "args": ["exec", "youtrack-mcp", "node", "build/index.js"],
      "env": {}
    }
  }
}

Configuration

Authentication Methods

Permanent Token (Recommended)

YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud
YOUTRACK_TOKEN=your-permanent-token

To create a permanent token:

1. Go to YouTrack → Profile → Account Security → Tokens
2. Click "New Token"
3. Set appropriate permissions and scope
4. Copy the generated token

Username/Password (Not Recommended)

YOUTRACK_BASE_URL=https://your-instance.youtrack.cloud
YOUTRACK_USERNAME=your-username
YOUTRACK_PASSWORD=your-password

Advanced Configuration

# Performance
YOUTRACK_REQUEST_TIMEOUT=30000
YOUTRACK_MAX_RETRIES=3
YOUTRACK_DEFAULT_PAGE_SIZE=50
YOUTRACK_MAX_PAGE_SIZE=100

# Caching
YOUTRACK_ENABLE_CACHE=true
YOUTRACK_CACHE_TTL=300

# Debugging
YOUTRACK_DEBUG=true

Available Tools

Issue Management

| Tool | Description | |------|-------------| | youtrack_list_issues | List issues with filtering and pagination | | youtrack_get_issue | Get detailed issue information | | youtrack_create_issue | Create a new issue | | youtrack_update_issue | Update existing issue | | youtrack_delete_issue | Delete an issue | | youtrack_search_issues | Advanced issue search with query syntax | | youtrack_add_comment | Add comment to an issue | | youtrack_get_comments | Get all comments for an issue | | youtrack_update_comment | Update existing comment | | youtrack_delete_comment | Delete a comment | | youtrack_add_attachment | Add file attachment to issue | | youtrack_get_attachments | Get all attachments for an issue | | youtrack_link_issues | Create links between issues | | youtrack_get_issue_links | Get all links for an issue |

Project Management

| Tool | Description | |------|-------------| | youtrack_list_projects | List all accessible projects | | youtrack_get_project | Get detailed project information | | youtrack_create_project | Create a new project | | youtrack_update_project | Update project settings | | youtrack_delete_project | Delete a project | | youtrack_get_project_custom_fields | Get custom fields for project | | youtrack_add_project_custom_field | Add custom field to project | | youtrack_list_project_versions | List project versions/releases | | youtrack_create_project_version | Create new version/release |

User Management

| Tool | Description | |------|-------------| | youtrack_list_users | List all users | | youtrack_get_user | Get user details | | youtrack_get_current_user | Get current authenticated user | | youtrack_list_groups | List user groups | | youtrack_get_group | Get group details | | youtrack_list_roles | List available roles |

Workflow Management

| Tool | Description | |------|-------------| | youtrack_get_workflow_states | Get available workflow states | | youtrack_get_workflow_transitions | Get possible state transitions | | youtrack_apply_workflow_command | Apply workflow command to issue | | youtrack_get_issue_commands | Get available commands for issue |

Time Tracking

| Tool | Description | |------|-------------| | youtrack_add_work_item | Add time tracking entry | | youtrack_get_work_items | Get work items for issue | | youtrack_update_work_item | Update work item | | youtrack_delete_work_item | Delete work item | | youtrack_get_time_tracking_report | Generate time tracking report |

Reports & Analytics

| Tool | Description | |------|-------------| | youtrack_get_project_statistics | Get project statistics | | youtrack_get_issue_statistics | Get issue-related statistics | | youtrack_generate_report | Generate custom reports | | youtrack_get_burndown_data | Get burndown chart data |

Agile & Boards

| Tool | Description | |------|-------------| | youtrack_list_agile_boards | List all agile boards | | youtrack_get_agile_board | Get agile board details | | youtrack_create_agile_board | Create new agile board | | youtrack_update_agile_board | Update agile board | | youtrack_list_sprints | List sprints for board | | youtrack_create_sprint | Create new sprint | | youtrack_update_sprint | Update sprint details |

Usage Examples

Creating an Issue

Create a new bug report with title "Login button not working" in project "WEB" with high priority

Searching Issues

Find all open issues assigned to john.doe in the mobile project created in the last 30 days

Project Management

List all projects and show their current status and team members

Time Tracking

Add 2 hours of development work to issue WEB-123 with description "Implemented login validation"

Workflow Management

Move issue WEB-123 to "In Progress" state and assign it to jane.smith

Development

Testing Installation

# Run comprehensive tests
./examples.sh

# Test specific components
./examples.sh npx        # Test npx installation
./examples.sh global     # Test global installation  
./examples.sh claude     # Generate Claude configs
./examples.sh docker     # Test Docker setup

Building

npm run build

Development Mode

npm run dev

Watch Mode

npm run watch

Testing

npm test
npm run test:npx      # Test npx functionality
npm run test:global   # Test global installation

Linting

npm run lint
npm run lint:fix

Debugging with MCP Inspector

npm run inspector

API Documentation

This MCP server follows YouTrack's REST API structure. For detailed API reference, visit:

• YouTrack REST API Documentation
• YouTrack API Reference

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Issues: GitHub Issues
• Documentation: API Documentation
• Community: Discussions

Acknowledgments

• JetBrains YouTrack for the excellent issue tracking platform
• Model Context Protocol for the standardized integration framework
• Anthropic Claude for AI assistant integration