youtrack-mcp

An MCP server for YouTrack, built with TypeScript and Bun. It works against any YouTrack instance (Cloud or self-hosted) — you supply the base URL and an API token, nothing is hardcoded.

Setup

You need a YouTrack permanent token: in YouTrack, go to your profile → Account Security → New token....

Set two environment variables:

• YOUTRACK_BASE_URL — the REST API base URL of your instance, e.g. https://mycompany.youtrack.cloud/api or https://youtrack.mycompany.com/api for self-hosted installs.
• YOUTRACK_TOKEN — the permanent token.

Install dependencies with Bun:

bun install

Run directly

YOUTRACK_BASE_URL=https://mycompany.youtrack.cloud/api YOUTRACK_TOKEN=perm:xxxx bun run src/index.ts

Configure in an MCP client

For example, in Claude Code / Claude Desktop's mcp.json:

{
  "mcpServers": {
    "youtrack": {
      "command": "bun",
      "args": ["run", "/path/to/youtrack-mcp/src/index.ts"],
      "env": {
        "YOUTRACK_BASE_URL": "https://mycompany.youtrack.cloud/api",
        "YOUTRACK_TOKEN": "perm:xxxx"
      }
    }
  }
}

Tools

Tools are grouped by resource and share a fields argument (YouTrack's partial-response syntax) with a sensible default, so you only need to specify it when you want more or less data back.

• Issues — list_issues (search), get_issue, create_issue, update_issue, delete_issue, execute_command (apply any YouTrack command — state, assignee, priority, links, tags, sprint, etc. via its natural query syntax, e.g. "State Fixed assignee John.Doe")
• Comments — list_issue_comments, add_issue_comment, update_issue_comment, delete_issue_comment
• Links — list_issue_links, list_issue_link_types
• Tags — list_tags, create_tag, list_issue_tags, add_issue_tag, remove_issue_tag
• Time tracking — list_issue_work_items, add_issue_work_item, update_issue_work_item, delete_issue_work_item, list_work_items
• Projects — list_projects, get_project, create_project, update_project, list_project_custom_fields
• Users & groups — get_current_user, list_users, get_user, list_groups
• Knowledge base — list_articles, get_article, create_article, update_article, delete_article
• Agile boards — list_agile_boards, get_agile_board, list_sprints, get_sprint
• Saved searches — list_saved_queries
• Escape hatch — youtrack_raw_request calls any endpoint of the YouTrack REST API directly (method, path, query, body), for the long tail of admin/settings endpoints not covered by a dedicated tool.

Design

• src/youtrack/client.ts — the only place that talks HTTP: auth header, URL/query building, JSON + error handling. Every tool goes through it.
• src/youtrack/fields.ts — default fields presets per entity, taken from YouTrack's own OpenAPI defaults.
• src/youtrack/params.ts — shared Zod schema fragments (fields, pagination, IDs) reused across tools.
• src/tool.ts — defineTool + registerTools, so each tool file only declares a name/description/schema/handler and the MCP response/error wrapping happens in one place.
• src/youtrack/tools/*.ts — one file per resource, each tool a few lines built on the shared pieces above.

Development

bun run typecheck   # tsc --noEmit
bun run dev         # run with --watch