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

Project Management

User Management

Workflow Management

Time Tracking

Reports & Analytics

Agile & Boards

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