YouTrack MCP Server for AI Assistants

Overview

This MCP (Model Context Protocol) server connects YouTrack to AI assistants so models can fetch issue context, run searches, and apply changes programmatically. It implements a set of MCP-compatible endpoints and “tools” that an assistant can call to answer questions about projects, summarize or triage issues, and perform updates (comments, state changes, assignments) while preserving YouTrack authentication and query semantics.

For developers building AI integrations, the server provides a lightweight bridge between an LLM-capable agent and YouTrack’s REST API. It centralizes common operations (search, fetch issue, list projects, update fields) and translates them into stable JSON RPC-like tool calls that follow MCP conventions, removing the need for each assistant integration to speak directly to YouTrack.

Features

• Exposes MCP-compatible tools for YouTrack operations (search, get, update, create, comment, attachments)
• Translates natural-language search into YouTrack query parameters (when used with a language model)
• Authenticated requests using YouTrack permanent tokens
• Local and containerized deployment (Node.js + Docker)
• Simple JSON-based tool payloads and responses suitable for chained LLM tool use
• Optional rate limiting and request logging for safe automation

Installation / Configuration

Prerequisites:

• Node.js 18+ (or a compatible runtime)
• A YouTrack instance and a personal access token with appropriate scopes

Clone and install:

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

Create a .env file (or set environment variables) with at least these values:

YOUTRACK_BASE_URL=https://youtrack.yourcompany.com
YOUTRACK_TOKEN=perm:XXXXXXXXXXXXXXXXXXXXX
MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=info

Run locally:

npm run build
npm start
# or for development
npm run dev

Run with Docker:

# build image
docker build -t youtrack-mcp .

# run container
docker run -d \
  -e YOUTRACK_BASE_URL=https://youtrack.yourcompany.com \
  -e YOUTRACK_TOKEN=perm:XXXXXXXXXXXXXXXX \
  -p 8080:8080 \
  --name youtrack-mcp \
  youtrack-mcp

Sample Docker Compose snippet:

version: "3.8"
services:
  youtrack-mcp:
    image: youtrack-mcp:latest
    environment:
      - YOUTRACK_BASE_URL=https://youtrack.yourcompany.com
      - YOUTRACK_TOKEN=perm:XXXXXXXXXXXXXXXX
    ports:
      - "8080:8080"

Security notes:

• Keep YOUTRACK_TOKEN secret and store it in a secure secret manager in production.
• Use TLS termination in front of the MCP server for encrypted transport.

Available Tools

The server exposes a set of MCP tools (JSON endpoints) intended to be called by an assistant. Each tool accepts a JSON payload and returns a JSON result. Below is a summary table:

Example: searchIssues payload

{
  "query": "project: MOBILE #Unresolved Type: Bug",
  "limit": 10,
  "fields": ["id", "summary", "assignee", "state"]
}

Response includes a list of simplified issue objects or full issue JSON depending on the fields requested.

Use Cases

1. Context-aware issue summarization

   • Scenario: An assistant receives a user question “What are the open frontend bugs blocking release?”
   • Flow:
     1. Assistant calls searchIssues with a query like project: FRONEND state: Open priority: High.
     2. MCP returns issues with summary and state.
     3. Assistant generates a consolidated summary and suggested next steps.

2. Triage and automated field updates

   • Scenario: A bot triages incoming issues and assigns them to owners.
   • Flow:
     1. Assistant calls getIssue to inspect the new ticket.
     2. Based on rules or an LLM prompt, assistant calls updateIssue to set an assignee and update the priority.
     3. Assistant adds a comment describing triage rationale via addComment.

3. Natural-language search and navigation

   • Scenario: “Show me all tasks assigned to Alice last week with tag regression.”
   • Flow:
     1. Assistant translates natural language to a YouTrack query (e.g., assignee: alice created: {last week} tag: regression) then calls searchIssues.
     2. Returns a short list that the user can expand or ask follow-up questions about.

4. Creating issues from chat

   • Scenario: A user reports a bug in a chat channel.
   • Flow:
     1. Assistant collects title, description, priority and optionally attachments.
     2. Assistant calls createIssue and attachFile to create the YouTrack ticket and attach logs/screenshots.
     3. Assistant returns the new issue ID and URL in chat.

Tips and Best Practices

• Limit the fields requested in search to reduce payload size; request full issue details only when needed.
• Implement server-side rate limiting to avoid hitting YouTrack API quotas.
• Use role-scoped tokens for automated bots and restrict scopes to only the needed permissions.
• Log tool calls for traceability, but avoid logging secrets or full token values.

For full API semantics and example requests/responses, consult the repository’s code and OpenAPI/MCP manifest (if included) to tailor the tool payloads to your assistant’s MCP implementation.