youtrack-mcp

A Model Context Protocol (MCP) server for YouTrack, exposing issues, comments, work items, projects, knowledge base articles, agile boards and sprints, and users as MCP tools.

Overview

This server uses the Rust MCP SDK (rmcp) to expose a YouTrack instance's REST API as MCP tools that an AI agent can call. It authenticates with a permanent API token and talks to the YouTrack REST API via the youtrack-client crate (from the youtrack-cli repo), so authentication and API calls reuse the same code path as the yt CLI rather than reimplementing them. It speaks MCP over stdio.

Configuration

The server is configured entirely through environment variables:

Variable	Required	Description
YOUTRACK_BASE_URL	yes	Base URL of the YouTrack instance (e.g. https://youtrack.example.com).
YOUTRACK_TOKEN	yes	Permanent API token used to authenticate.
RUST_LOG	no	Log filter (logs go to stderr; stdout carries the JSON-RPC stream). Defaults to youtrack_mcp=info.

Tools

The server exposes the following tools, grouped by domain:

• Issues: search_issues, get_issue, create_issue, update_issue, delete_issue, apply_command, get_issue_activities, list_issue_custom_fields, list_issue_attachments, list_link_types
• Comments: list_comments, add_comment
• Work items (time tracking): list_work_items, add_work_item, delete_work_item
• Projects: list_projects, get_project, list_project_states, list_project_vcs_processors
• Articles (knowledge base): list_articles, get_article, create_article, update_article, delete_article
• Agile boards & sprints: list_boards, list_sprints, set_issue_sprint
• Users: get_current_user, list_users, get_user

apply_command is the way to change issue state, assignee, priority, type, tags, and estimation, since YouTrack models those as commands rather than direct field writes. The command value is project-specific (e.g. State Done, Assignee me, Priority Critical, tag regression); use list_project_states to discover the valid State values for a project.

Usage

Run the server over stdio:

cargo run

Most MCP clients launch the binary themselves; configure the client to run the youtrack-mcp binary with the required environment variables set.

Example claude registration (stdio transport):

claude mcp add youtrack --env YOUTRACK_BASE_URL=https://youtrack.example.com --env YOUTRACK_TOKEN=perm:... -- /absolute/path/to/youtrack-mcp

Development

This repo uses a justfile for the standard dev workflow. Run just (or just --list) to see every recipe.

just install-hooks   # one-time per clone: install the pre-commit hook
just check           # fmt + clippy + build + builder-stage docker compile
just test            # cargo test
just build           # release binary
just build-docker-export   # extract the dynamic glibc Linux binary via the OCI build
just build-static          # build the fully static musl Linux binary via Docker
just build-windows         # cross-compile the Windows .exe
just create-release minor  # bump version, push release branch, open the PR via fj

just pre-commit runs the same fmt + clippy + build + test steps as .forgejo/workflows/check.yml, inside the rust-builder-glibc image so the toolchain matches CI. Conventions follow the a8n-run/governance repo; see CLAUDE.md for youtrack-mcp-specific notes.

Releases

CI publishes binaries to the Forgejo Generic Packages registry on every push to main and on v* tags:

Artifact	Target	Linking
youtrack-mcp-linux-x86_64	x86_64-unknown-linux-gnu	Dynamic glibc.
youtrack-mcp-linux-x86_64-static	x86_64-unknown-linux-musl	Fully static (rustls, no OpenSSL; runs on any Linux).
youtrack-mcp-windows-x86_64.exe	x86_64-pc-windows-gnu	mingw cross-compile.

just create-release <major|minor|hotfix> opens the release PR; once merged, .forgejo/workflows/create-release.yml tags and publishes automatically.

Other implementations

Other MCP servers for YouTrack:

• tonyzorin/youtrack-mcp
• pushax/youtrack-mcp
• GaijinEntertainment/youtrack-rocket-mcp

License

Licensed under the MIT License (LICENSE.md), matching the youtrack-client crate this depends on.