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.

The server has two transports, selected with --transport / YT_MCP_TRANSPORT:

• stdio (default): a single-identity binary an MCP client launches itself, authenticated by one YOUTRACK_TOKEN. This is the mode described below.
• http: a multi-user, internet-facing service that logs each user in against YouTrack Hub (OAuth 2.1), gates access by an allowlist, and serves a per-user Streamable HTTP /mcp endpoint for Claude on the web. Deploy it behind a TLS-terminating reverse proxy; see docs/deployment.md, compose.yml, and .env.example.

Configuration

The stdio server is configured entirely through environment variables. Every one of them configures how the server reaches YouTrack. stdio mode has no inbound authentication: the MCP client that launches the binary owns the process over stdin/stdout, so there is no client-to-server token. (Coming from forgejo-mcp? There is no MCP_HTTP_TOKEN-style inbound bearer here. Inbound, per-user authentication exists only in the http transport, which logs each user in via OAuth 2.1 against YouTrack Hub.)

Variable	Required	Direction	Description
YOUTRACK_BASE_URL	yes	server to YouTrack	Base URL the server calls (e.g. https://youtrack.example.com).
YOUTRACK_TOKEN	yes	server to YouTrack	Permanent YouTrack API token the server presents to authenticate itself to YouTrack (upstream). This is not an inbound or client-facing bearer; stdio mode has no inbound auth.
RUST_LOG	no	n/a	Log filter (logs go to stderr; stdout carries the JSON-RPC stream). Defaults to youtrack_mcp=info.

The HTTP service mode reads a larger set of variables (public URL, Hub OAuth client, master/session keys, SQLite path); .env.example and docs/deployment.md document them in full.

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
• Gantt / scheduling: get_issue_timeline, link_issues, remove_issue_link, list_issue_links, set_issue_schedule
• 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          # build the HTTP service image (Dockerfile.static runtime stage)
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-musl image so the toolchain matches the shipped static binary and the HTTP service image. 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-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.