YouTrack

YouTrack MCP Server lets you connect YouTrack data to an MCP client, giving you powerful issue tracking, project management, workflows, and analytics. It enables you to operate and automate YouTrack from your preferred MCP-enabled tools and environments, so you can build integrated workflows and custom UI experiences without manual handoffs.

How to use

You connect to the MCP server from an MCP client by choosing a local (stdio) runtime or a remote configuration, then start the server using the provided command. Once running, you can list, create, update, and search issues, manage projects and sprints, define workflows, and automate actions across your YouTrack instance. Use environment variables to provide authentication details and base URLs, and adjust performance and caching settings as needed. You can run multiple MCP configurations side by side, each with its own env and command.

How to install

Prerequisites: ensure you have Node.js 18.0.0 or higher and a YouTrack instance (Cloud or On-Premise) with an API token or credentials.

Choose one of the lightweight installation options to start quickly without heavy node_modules.

Follow steps exactly as shown to run locally or in Claude/Docker environments.

Lightweight installation options

# 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 to enable MCP server integration with Claude on macOS or Windows.

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

Configuration

Authentication methods include a permanent token or username/password. Prefer a permanent token for secure, long-term access.

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

Advanced options cover performance, caching, and debugging. Adjust request timeout, retries, cache TTL, and enable debug logging as needed.

# 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 and actions

You can perform a wide range of operations through MCP commands, including listing, creating, updating, deleting, and querying issues, managing projects and versions, handling users and teams, applying workflows, and generating reports.

Available tools

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 a comment to an issue

youtrack_get_comments

Get all comments for an issue

youtrack_update_comment

Update an existing comment

youtrack_delete_comment

Delete a comment

youtrack_add_attachment

Add a file attachment to an 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

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

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

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

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

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

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