YouTrack MCP Server

A Model Context Protocol (MCP) server for JetBrains YouTrack, enabling seamless integration with Claude Desktop and other MCP clients.

Quick Start

Choose your preferred installation method:

Option 1: npm/Node.js (Recommended)

Installation:

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

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

Usage:

# Run with stdio transport (for Claude Desktop)
npx agentek-youtrack-mcp

# Run with HTTP transport
npx agentek-youtrack-mcp --http --port 8000

# Show help
npx agentek-youtrack-mcp --help

Option 2: Docker

Using Docker Hub:

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

Available Docker Tags:

• latest - Latest build from the main branch
• 1.0.0 - Specific release version tags
• <commit-sha> - Exact commit builds

Configuration

Environment Variables

Set these environment variables for both npm and Docker options:

export YOUTRACK_URL="https://your.youtrack.cloud"
export YOUTRACK_API_TOKEN="your-token"
export YOUTRACK_VERIFY_SSL="true"  # Optional, default: true

Claude Desktop Integration

Choose your preferred method:

Using npm/Node.js:

{
  "mcpServers": {
    "youtrack": {
      "command": "npx",
      "args": ["agentek-youtrack-mcp"],
      "env": {
        "YOUTRACK_URL": "https://your.youtrack.cloud",
        "YOUTRACK_API_TOKEN": "your-token"
      }
    }
  }
}

Using Docker Hub:

{
  "mcpServers": {
    "youtrack": {
      "command": "docker",
      "args": [
        "run", "--rm",
        "-e", "YOUTRACK_URL=https://your.youtrack.cloud",
        "-e", "YOUTRACK_API_TOKEN=your-token",
        "windbit/agentek-youtrack-mcp:latest"
      ]
    }
  }
}

Using GitHub Container Registry:

{
  "mcpServers": {
    "youtrack": {
      "command": "docker",
      "args": [
        "run", "--rm",
        "-e", "YOUTRACK_URL=https://your.youtrack.cloud",
        "-e", "YOUTRACK_API_TOKEN=your-token",
        "ghcr.io/windbit/agentek-youtrack-mcp:latest"
      ]
    }
  }
}

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

Requirements

For npm/Node.js option:

• Node.js: 18.0.0 or higher
• Python: 3.8 or higher (automatically detected)
• YouTrack: Cloud or Server instance with API access

For Docker option:

• Docker: Latest version
• YouTrack: Cloud or Server instance with API access

Note: Docker option includes all dependencies pre-installed

API Commands

Once configured, you can use these commands in Claude:

• Create, update, and manage YouTrack issues
• Search issues with advanced filters
• Access project information and custom fields
• Download, analyze, and delete issue attachments
• Manage user permissions and assignments

CLI Options

Usage:
  npx agentek-youtrack-mcp [options] [-- server-args]

Options:
  --help, -h           Show help message
  --version, -v        Show version information
  --info               Show server information
  --stdio              Use stdio transport (default)
  --http               Use HTTP transport
  --host <host>        Host to bind HTTP server (default: 0.0.0.0)
  --port <port>        Port for HTTP server (default: 8000)

Environment Variables:
  YOUTRACK_URL          Your YouTrack instance URL (required)
  YOUTRACK_API_TOKEN    Your YouTrack API token (required)
  YOUTRACK_VERIFY_SSL   Verify SSL certificates (default: true)

Examples

Basic Usage

npm/Node.js:

# Set environment variables
export YOUTRACK_URL="https://prodcamp.youtrack.cloud"
export YOUTRACK_API_TOKEN="your-token"

# Run the server
npx agentek-youtrack-mcp

Docker Hub:

# Run with environment variables
docker run --rm \
  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  windbit/agentek-youtrack-mcp:latest

GitHub Container Registry:

# Run with environment variables
docker run --rm \
  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  ghcr.io/windbit/agentek-youtrack-mcp:latest

HTTP Mode

npm/Node.js:

# Start HTTP server on port 8000
npx agentek-youtrack-mcp --http --port 8000

# Test the server
curl http://localhost:8000/api/tools

Docker Hub:

# Start HTTP server with port mapping
docker run --rm -p 8000:8000 \
  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  windbit/agentek-youtrack-mcp:latest --transport http --host 0.0.0.0

# Test the server
curl http://localhost:8000/api/tools

GitHub Container Registry:

# Start HTTP server with port mapping
docker run --rm -p 8000:8000 \
  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  ghcr.io/windbit/agentek-youtrack-mcp:latest --transport http --host 0.0.0.0

# Test the server
curl http://localhost:8000/api/tools

Development Mode

npm/Node.js:

# Run with debug logging
npx agentek-youtrack-mcp -- --log-level DEBUG

Docker Hub:

# Run with debug logging
docker run --rm \
  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  windbit/agentek-youtrack-mcp:latest --log-level DEBUG

GitHub Container Registry:

# Run with debug logging
docker run --rm \
  -e YOUTRACK_URL="https://prodcamp.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  ghcr.io/windbit/agentek-youtrack-mcp:latest --log-level DEBUG

Troubleshooting

npm/Node.js Issues

Python Not Found

If you get a "Python not found" error:

# Install Python 3.8+
# macOS with Homebrew:
brew install python

# Ubuntu/Debian:
sudo apt-get install python3

# Windows: Download from python.org

Permission Errors

# Check your YouTrack API token
npx agentek-youtrack-mcp --info

# Verify your environment variables
echo $YOUTRACK_URL
echo $YOUTRACK_API_TOKEN

Docker Issues

Container Won't Start

# Check Docker is running
docker --version

# Check container logs
docker run --rm \
  -e YOUTRACK_URL="https://your.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  windbit/agentek-youtrack-mcp:latest --version

Port Already in Use

# Use a different port
docker run --rm -p 8001:8000 \
  -e YOUTRACK_URL="https://your.youtrack.cloud" \
  -e YOUTRACK_API_TOKEN="your-token" \
  windbit/agentek-youtrack-mcp:latest --transport http

GitHub Container Registry Authentication

# If you get pull errors from ghcr.io, you might need to authenticate
docker login ghcr.io

# Then try pulling again
docker pull ghcr.io/windbit/agentek-youtrack-mcp:latest

Common Issues (Both Options)

Connection Issues

If you can't connect to YouTrack:

• Verify your YouTrack URL is correct
• Check that your API token has proper permissions
• Ensure your network allows connections to YouTrack
• Try testing the API token manually:

  curl -H "Authorization: Bearer your-token" \
       "https://your.youtrack.cloud/api/admin/projects"

Which Option Should I Choose?

Choose npm/Node.js if you:

• ✅ Already have Node.js installed
• ✅ Want faster startup times
• ✅ Prefer lighter resource usage
• ✅ Need to modify or debug the server

Registry Options:

• npmjs.org: agentek-youtrack-mcp

Choose Docker if you:

• ✅ Want isolated, consistent environments
• ✅ Don't want to install Node.js/Python
• ✅ Are running in containerized infrastructure
• ✅ Want guaranteed dependency compatibility

Registry Options:

• Docker Hub (recommended): windbit/agentek-youtrack-mcp - Faster, no auth required
• GitHub Container Registry: ghcr.io/windbit/agentek-youtrack-mcp - Integrated with GitHub, may require auth

Support

• GitHub: Issues and bug reports
• Documentation: Full documentation

Package Registries

• Docker Hub: windbit/agentek-youtrack-mcp
• GitHub Container Registry: ghcr.io/windbit/agentek-youtrack-mcp
• npmjs.org: agentek-youtrack-mcp

License

MIT