Skip to main content
Glama
VitalyOstanin

YouTrack MCP Server

by VitalyOstanin
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

YouTrack MCP Server

Also available in Russian: README-ru.md

CI codecov npm version

MCP server for comprehensive YouTrack integration with the following capabilities:

  • Issue management - create, update, comment, assign, change state, batch operations

  • Issue starring - mark important issues with stars, batch starring (up to 50), list starred issues

  • Attachment management - upload files (up to 10), download with signed URLs, delete

  • Work items tracking - create entries with idempotent operations, batch creation for periods

  • Detailed time reports - summary reports, deviation analysis, multi-user statistics

  • Advanced search - find issues by user activity with fast/precise filtering modes

  • Change history - complete issue activity log with filtering and pagination

  • Knowledge base - create, update, search articles with hierarchical structure

  • User and project access - retrieve information about users and projects

  • Batch operations - efficient processing of up to 50 issues simultaneously

  • File storage - save large tool results to JSON files instead of returning directly

  • Additional features - Markdown support, folded sections, holiday configuration, user aliases

Table of Contents

Related MCP server: Jira MCP Server

Requirements

  • Node.js ≥ 22

  • Environment variables:

    • YOUTRACK_URL — base URL of YouTrack instance

    • YOUTRACK_TOKEN — permanent token with read permissions for issues and work items

    • YOUTRACK_TIMEZONE — optional timezone for date operations (default: Europe/Moscow), must be a valid IANA timezone identifier (e.g., Europe/London, America/New_York, Asia/Tokyo)

    • YOUTRACK_HOLIDAYS — optional comma-separated list of holiday dates (format YYYY-MM-DD), excluded from reports and batch operations

  • YOUTRACK_PRE_HOLIDAYS — optional comma-separated list of pre-holiday dates with reduced working hours

  • YOUTRACK_USER_ALIASES — optional comma-separated list of alias:login mappings (e.g., me:vyt,petya:p.petrov), used for automatic assignee selection

  • YOUTRACK_DEFAULT_PROJECT — optional project code used for manual verification tasks and default parent issues in docs/examples (use PROJ in documentation examples)

  • YOUTRACK_OUTPUT_DIR — optional root directory for files produced by saveToFile and downloadToFile. Defaults to the current working directory. Absolute paths and parent-traversal segments (..) are rejected for safety

  • YOUTRACK_UPLOAD_DIR — optional whitelist root for source files used by issue_attachment_upload. Defaults to YOUTRACK_OUTPUT_DIR. Paths whose realpath escapes this directory (including via symlinks) are rejected to prevent reading arbitrary files (/etc/passwd, ~/.ssh/id_rsa, etc.)

Installation

Using npx (Recommended)

You can run the server directly with npx without installation:

YOUTRACK_URL="https://youtrack.example.com" \
YOUTRACK_TOKEN="perm:your-token-here" \
YOUTRACK_DEFAULT_PROJECT="PROJ" \
npx -y @vitalyostanin/youtrack-mcp@latest

Using Claude MCP CLI

Install using Claude MCP CLI:

claude mcp add --scope user \
--env YOUTRACK_URL='https://youtrack.example.com' \
--env YOUTRACK_TOKEN='perm:my-token' \
youtrack-mcp -- npx -y @vitalyostanin/youtrack-mcp@latest

Scope Options:

  • --scope user: Install for current user (all projects)

  • --scope project: Install for current project only

Removal:

claude mcp remove youtrack-mcp --scope user

Manual Installation (Development)

npm install
npm run build

Development & Release

GitHub Actions Workflows

This project uses GitHub Actions for continuous integration and automated releases:

CI Workflow (.github/workflows/ci.yml)

Runs automatically on every push and pull request:

  • Triggers: All branches, all pull requests

  • Node.js versions: 22.x, 24.x (matrix testing)

  • Steps:

    1. Install dependencies (npm ci)

    2. Run linter (npm run lint)

    3. Build project (npm run build)

    4. Verify build artifacts (executable check)

Publish Workflow (.github/workflows/publish.yml)

Runs automatically when you create a new version tag:

  • Trigger: Git tags matching v* pattern (e.g., v0.1.0, v1.2.3)

  • Node.js version: 24.x

  • Steps:

    1. Install dependencies

    2. Build project

    3. Publish to npm registry

    4. Create GitHub Release

Setting up NPM_TOKEN

To enable automatic publishing to npm, you need to configure the NPM_TOKEN secret:

  1. Generate npm Access Token:

    • Go to npmjs.com and log in

    • Navigate to Access Tokens in your account settings

    • Click Generate New Token → Classic Token

    • Select Automation type (for CI/CD)

    • Copy the generated token

  2. Add Secret to GitHub:

    • Go to your GitHub repository

    • Navigate to Settings → Secrets and variables → Actions

    • Click New repository secret

    • Name: NPM_TOKEN

    • Value: Paste your npm token

    • Click Add secret

Release Process

To create a new release:

# 1. Update version in package.json and create git tag
npm version patch   # for 0.1.0 → 0.1.1
# or
npm version minor   # for 0.1.0 → 0.2.0
# or
npm version major   # for 0.1.0 → 1.0.0

# 2. Push the tag to GitHub
git push --follow-tags

# 3. GitHub Actions will automatically:
#    - Run tests and build
#    - Publish to npm
#    - Create GitHub Release

Note: The npm version command automatically:

  • Updates package.json and package-lock.json

  • Creates a git commit with message like "0.1.1"

  • Creates a git tag like "v0.1.1"

Manual Build & Test

# Install dependencies
npm install

# Build the project
npm run build

# Run linter
npm run lint

# Watch mode for development
npm run dev:watch

Project Structure

src/
  index.ts                MCP server entry point (stdio transport)
  server.ts               MCP server bootstrap, tool registration
  config.ts               YOUTRACK_* environment variable parsing
  constants.ts            HTTP timeouts, body limits, PRE_HOLIDAY_RATIO
  types.ts                Shared TypeScript interfaces and YouTrack entity discriminators
  youtrack-client.ts      YouTrack REST client with caching and pagination helpers
  tools/                  MCP tool registrations (one file per domain: issues, articles, ...)
  utils/                  Reusable helpers (date, file-storage, mappers, validators, tool-args, ...)
  __tests__/              Vitest tests against a nock-mocked HTTP layer
docs/
  reviews/                Project-check review reports
.github/
  workflows/              CI and publish workflows
  dependabot.yml          Weekly npm + github-actions update PRs
dist/                     Build output (generated by `npm run build`, gitignored)

The authoritative agent-oriented project layout lives in AGENTS.md.

Running the server (stdio)

YOUTRACK_URL="https://youtrack.example.com" \
YOUTRACK_TOKEN="perm:example-token" \
node dist/index.js

Configuration for Code (Recommended)

Add to ~/.code/config.toml:

[mcp_servers.youtrack-mcp]
command = "npx"
args = ["-y", "@vitalyostanin/youtrack-mcp@latest"]

[mcp_servers.youtrack-mcp.env]
YOUTRACK_URL = "https://youtrack.example.com"
YOUTRACK_TOKEN = "perm:your-token-here"

Configuration for Claude Code CLI

To use this MCP server with Claude Code CLI, you can:

  1. Use Claude MCP CLI - see Installation section above

  2. Manual configuration - add to your ~/.claude.json file:

{
  "mcpServers": {
    "youtrack-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@vitalyostanin/youtrack-mcp@latest"],
      "env": {
        "YOUTRACK_URL": "https://youtrack.example.com",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

Note: This configuration uses npx to run the published package. For local development, use "command": "node" with "args": ["/absolute/path/to/youtrack-mcp/dist/index.js"]. The YOUTRACK_TIMEZONE, YOUTRACK_HOLIDAYS, YOUTRACK_PRE_HOLIDAYS, and YOUTRACK_USER_ALIASES environment variables are optional.

Configuration for VS Code Cline

To use this MCP server with Cline extension in VS Code:

  1. Open VS Code with Cline extension installed

  2. Click the MCP Servers icon in Cline's top navigation

  3. Select the "Configure" tab and click "Configure MCP Servers"

  4. Add the following configuration to cline_mcp_settings.json:

{
  "mcpServers": {
    "youtrack-mcp": {
      "command": "npx",
      "args": ["-y", "@vitalyostanin/youtrack-mcp@latest"],
      "env": {
        "YOUTRACK_URL": "https://youtrack.example.com",
        "YOUTRACK_TOKEN": "perm:your-token-here"
      }
    }
  }
}

Note: This configuration uses npx to run the published package. For local development, use "command": "node" with "args": ["/absolute/path/to/youtrack-mcp/dist/index.js"]. The YOUTRACK_TIMEZONE, YOUTRACK_HOLIDAYS, YOUTRACK_PRE_HOLIDAYS, and YOUTRACK_USER_ALIASES environment variables are optional.

MCP Tools

File Storage Parameters

Many tools support optional file storage parameters for handling large datasets:

  • saveToFile — boolean, saves results to a JSON file instead of returning directly (useful for large datasets)

  • filePath — string, custom file path relative to YOUTRACK_OUTPUT_DIR (optional, auto-generated if not provided, directory created if needed)

  • format — string, output format when saving to file: jsonl (JSON Lines) or json (JSON array format). Default is jsonl

  • overwrite — boolean, allow overwriting existing files when using explicit filePath. Default is false

When saveToFile is true, tools return metadata about the saved file instead of the full data. All paths are resolved against YOUTRACK_OUTPUT_DIR; absolute paths and .. traversal segments are rejected.

Pagination

Most read tools accept limit (default 100, max 200) and skip (default 0); both are forwarded to YouTrack as $top/$skip. Tools that return aggregated counts use returned (count of items in the current page) rather than total. Use successive skip values to walk through large result sets.

Destructive Operation Confirmation

Tools that delete data require an explicit confirmation: true literal in their input:

  • issue_attachment_delete

  • issue_link_delete

  • workitem_delete

Service

Tool

Description

Main Parameters

service_info

Check YouTrack availability and current user

—

Issues

Tool

Description

Main Parameters

issue_lookup

Get information about YouTrack issue. Note: Returns predefined fields including timestamps (created, updated) and basic info - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). By default, custom fields are not included. Use briefOutput=false to get all customFields including State.

issueId — issue code (e.g., PROJ-123); briefOutput — optional boolean (default true)

issues_lookup

Get information about multiple YouTrack issues (batch mode, max 50). Note: Returns predefined fields including timestamps (created, updated) and basic info - id, idReadable, summary, description, wikifiedDescription, usesMarkdown, created, updated, project (id, shortName, name), parent (id, idReadable), assignee (id, login, name), reporter (id, login, name), updater (id, login, name). By default, custom fields are not included. Use briefOutput=false to get all customFields including State.

issueIds[] — array of issue codes (e.g., ['PROJ-123', 'PROJ-124']), max 50; briefOutput — optional boolean (default true)

issue_details

Issue details with brief/full modes

issueId — issue code; briefOutput — optional boolean (default true). Brief: predefined fields only. Full (false): adds customFields including State; saveToFile, filePath, format, overwrite — file storage options

issues_details

Detailed information about multiple issues (batch mode, max 50). Brief (default): predefined fields only. Full (briefOutput=false): adds customFields for each issue

issueIds[] — array of issue codes, max 50; briefOutput — optional boolean (default true); saveToFile, filePath, format, overwrite — file storage options

issue_comments

Issue comments with server-side pagination

issueId — issue code; limit (default 100, max 200), skip for pagination; saveToFile, filePath, format, overwrite — file storage options

issues_comments

Comments for multiple issues (batch mode, max 50)

issueIds[] — array of issue codes, max 50; briefOutput — optional boolean (default true); saveToFile, filePath, format, overwrite — file storage options

issue_create

Create issue

projectId, summary, optional description, parentIssueId, assigneeLogin, stateName, usesMarkdown, links (array of link objects)

issue_update

Update existing issue

issueId, optionally summary, description, parentIssueId (empty string clears parent), usesMarkdown

issue_assign

Assign issue to user

issueId, assigneeLogin (login or me)

issue_comment_create

Add comment to issue

issueId, text — comment text, optionally usesMarkdown

issue_comment_update

Update existing comment

issueId, commentId, optionally text, usesMarkdown, muteUpdateNotifications

issue_activities

Get issue change history

issueId — issue code, optionally author (login), startDate (YYYY-MM-DD, timestamp, or Date), endDate, categories (comma-separated: CustomFieldCategory for field changes, CommentsCategory for comments, AttachmentsCategory for attachments, LinksCategory for links, VcsChangeActivityCategory for VCS changes, WorkItemsActivityCategory for work items), limit (max 200), skip for pagination; saveToFile, filePath, format, overwrite — file storage options. Returns activity items with timestamps (ISO datetime), authors, categories, and change details (added/removed values). Useful for tracking field modifications, reviewing comment history, and analyzing collaboration patterns

issue_change_state

Change issue state/status through workflow transitions

issueId — issue code, stateName — target state name (e.g., 'In Progress', 'Open', 'Fixed', 'Verified'). Case-insensitive. Automatically discovers available transitions and validates requested state change. Returns information about previous state, new state, and transition used. Use for moving issues through workflow states

issue_attachments_list

Get list of attachments

issueId — issue code; saveToFile, filePath, format, overwrite — file storage options

issue_attachment_get

Get attachment info

issueId, attachmentId; saveToFile, filePath, format, overwrite — file storage options

issue_attachment_download

Get download URL for attachment or download file directly to local filesystem

issueId, attachmentId — returns signed download URL when downloadToFile=false; downloadToFile — boolean, download file directly to local system (default: false); downloadPath — custom path to save file (auto-generated if not provided); overwrite — allow overwriting existing files (default: false, throws error if file exists); saveToFile, filePath, format, overwrite — file storage options for metadata

issue_attachment_upload

Upload files to issue

issueId, filePaths[] — array of file paths (max 10), optionally muteUpdateNotifications

issue_attachment_delete

Delete attachment (requires confirmation: true)

issueId, attachmentId, confirmation (must be the boolean literal true)

Issue Links

Tool

Description

Main Parameters

issue_links

List links for an issue with server-side pagination. Returns link id, direction, linkType, and counterpart issue brief

issueId — issue code; limit (default 100, max 200), skip for pagination

issue_link_types

List available link types (cached single-flight)

—

issue_link_add

Create a link between two issues

sourceId, targetId, linkType (name or id), optionally direction (outbound or inbound)

issue_link_delete

Delete a link by id for a specific issue (requires confirmation: true)

issueId, linkId, optionally targetId, confirmation (must be the boolean literal true)

Issues Status

Tool

Description

Main Parameters

issue_status

Get status of a YouTrack issue. Returns the State of the issue.

issueId — issue code (e.g., PROJ-123)

issues_status

Get status of multiple YouTrack issues (batch mode, max 50). Returns the State of each issue.

issueIds[] — array of issue codes (e.g., ['PROJ-123', 'PROJ-124']), max 50

Issue Stars

Tool

Description

Main Parameters

issue_star

Add star to issue for current user

issueId — issue code (e.g., PROJ-123). Idempotent operation - returns success even if already starred

issue_unstar

Remove star from issue for current user

issueId — issue code. Idempotent operation - returns success even if not currently starred

issues_star_batch

Add stars to multiple issues (batch mode, max 50)

issueIds[] — array of issue codes (max 50). Returns object with successful and failed arrays. Processes with concurrency limit (10 concurrent requests)

issues_unstar_batch

Remove stars from multiple issues (batch mode, max 50)

issueIds[] — array of issue codes (max 50). Returns object with successful and failed arrays. Processes with concurrency limit (10 concurrent requests)

issues_starred_list

Get all starred issues for current user

Optionally limit (default 50, max 200), skip for pagination. Returns array of starred issues with basic information (id, idReadable, summary, project, parent, assignee) without description fields

Work Items

Tool

Description

Main Parameters

workitems_list

Get work items for current or specified user with server-side pagination

Optionally issueId, author, startDate, endDate, allUsers; limit (default 100, max 200), skip for pagination; saveToFile, filePath, format, overwrite — file storage options

workitems_all_users

Get work items for all users with server-side pagination

Optionally issueId, startDate, endDate; limit (default 100, max 200), skip for pagination; saveToFile, filePath, format, overwrite — file storage options

workitems_for_users

Get work items for selected users with per-user pagination

users[], optionally issueId, startDate, endDate; limit (default 100, max 200), skip applied per user; saveToFile, filePath, format, overwrite — file storage options

workitems_recent

Get recent work items sorted by update time (newest first)

Optionally users[] (defaults to current user), limit (default 50, max 200); saveToFile, filePath, format, overwrite — file storage options

workitem_create

Create work item entry

issueId, date, minutes, optionally summary, description, usesMarkdown

workitem_create_idempotent

Create work item without duplicates (by description and date)

issueId, date, minutes, description, optionally usesMarkdown

workitem_update

Update work item (recreate)

issueId, workItemId, optionally date, minutes, summary, description, usesMarkdown

workitem_delete

Delete work item (requires confirmation: true)

issueId, workItemId, confirmation (must be the boolean literal true)

workitems_create_period

Batch create for date range

issueId, startDate, endDate, minutes, optionally summary, description, usesMarkdown, excludeWeekends, excludeHolidays, holidays[], preHolidays[]

workitems_report_summary

Summary report for work items

Common parameters: author, issueId, startDate, endDate, expectedDailyMinutes, excludeWeekends, excludeHolidays, holidays[], preHolidays[], allUsers; saveToFile, filePath, format, overwrite — file storage options

workitems_report_invalid

Days with deviation from expected hours

Same parameters as summary; saveToFile, filePath, format, overwrite — file storage options

workitems_report_users

Work items report for list of users

users[] + common report parameters; saveToFile, filePath, format, overwrite — file storage options

workitems_report

Report structure (compatibility with older clients)

Optionally author, issueId, startDate, endDate, expectedDailyMinutes, excludeWeekends, excludeHolidays, holidays[], preHolidays[], allUsers; saveToFile, filePath, format, overwrite — file storage options

Users and Projects

Tool

Description

Main Parameters

users_list

List all YouTrack users with server-side pagination

limit (default 100, max 200), skip for pagination; saveToFile, filePath, format, overwrite — file storage options

user_get

Get user by login

login — user login

user_current

Get current authenticated user

—

projects_list

List all YouTrack projects (auto-paginated by default; pass limit/skip for explicit paging)

Optional limit (max 200), skip

project_get

Get project by short name

shortName — project short name

Articles

Tool

Description

Main Parameters

article_get

Get article by ID

articleId

article_list

List articles with filters and server-side pagination

Optionally parentArticleId, projectId; limit (default 100, max 200), skip for pagination

article_create

Create article in knowledge base

summary, optionally content, parentArticleId, projectId, usesMarkdown, returnRendered

article_update

Update article

articleId, optionally summary, content, usesMarkdown, returnRendered

article_search

Search articles in knowledge base

query, optionally projectId, parentArticleId, limit, returnRendered; saveToFile, filePath, format, overwrite — file storage options

articles_search

Full-text search across YouTrack knowledge base articles by title and content. Returns webUrl for direct access.

query, limit, skip, optionally projectId, parentArticleId; saveToFile, filePath, format, overwrite — file storage options

issues_search

Full-text search across YouTrack issues by summary, description, and comments. If query is not provided or empty, all issues will be returned. Supports filtering by projects, assignee, reporter, state, and type.

query (optional), limit, skip, countOnly (optional), projects (optional), assignee (optional), reporter (optional), state (optional), type (optional); saveToFile, filePath, format, overwrite — file storage options

Search

Tool

Description

Main Parameters

articles_search

Full-text search across YouTrack knowledge base articles by title and content. Returns webUrl for direct access

query (min 2 chars), limit (default 50, max 200), skip, optionally projectId, parentArticleId

issues_search

Full-text search across YouTrack issues by summary, description, and comments. If query is not provided or empty, all issues will be returned. Supports filtering by projects, assignee, reporter, state, and type

query (optional), limit (default 50, max 200), skip, countOnly (optional), projects (optional), assignee (optional), reporter (optional), state (optional), type (optional)

Activity Feed

Tool

Description

Main Parameters

users_activity

Author-centric activity feed backed by /api/activities. Use for: auditing a teammate's updates, gathering comment/state changes across many issues, and reviewing deployment timelines. Returns normalized entries with ISO timestamps, optional issue references, and added/removed payloads. Always follow up by re-fetching the affected issue or work-item to confirm the latest state. Supported categories: CustomFieldCategory (field changes), CommentsCategory (comments), AttachmentsCategory (file events), LinksCategory (issue links), VcsChangeActivityCategory (VCS changes), WorkItemsActivityCategory (work items).

author (required) — login such as vyt; categories (required) — comma-separated list built from the supported categories above; optional start / end (ISO string, timestamp in ms, or Date) to bound the range, reverse (boolean) to switch to chronological order, limit (default 100, max 200), skip (pagination offset), fields (advanced override of response fields); saveToFile, filePath, format, overwrite — file storage options.

issues_list

List issues across projects with filtering and sorting

Filters: projectIds, createdAfter/Before, updatedAfter/Before, statuses, assigneeLogin, types; Sorting: sortField, sortDirection; Pagination: limit, skip; Output mode: briefOutput; saveToFile, filePath, format, overwrite — file storage options

issues_count

Count issues using same filters as issues_list, returns per-project breakdown

Same filters as above, optional top to cap manual aggregation when many projects are involved; saveToFile, filePath, format, overwrite — file storage options

Important Notes

Destructive Operations

Some operations cannot be undone and require an explicit confirmation: true literal in their input:

  • issue_attachment_delete — deleted attachments cannot be recovered.

  • issue_link_delete — re-fetch issue_links afterwards to verify the relationship was removed.

  • workitem_delete — work item entries are permanently lost; re-fetch workitems_list to confirm. issue_create parameters:

  • parentIssueId — resolves against YOUTRACK_DEFAULT_PROJECT when no project prefix is provided (e.g., 123 → BC-123 if default project is BC).

  • links[] — optional array describing additional links to create after the issue is saved. Each item supports:

    • linkType — name or id of the link type (e.g., Subtask, Relates).

    • targetId — issue id or readable id. Plain numbers are resolved with the default project, matching resolveIssueId behaviour.

    • direction — optional ("outbound" by default). Use "inbound" to flip direction for non-symmetric link types.

    • sourceId — optional. When omitted, the new issue is treated as the source. Specify to create links from an existing issue to the new one (useful for complex chains).

  • After creation the tool automatically refreshes the issue and attempts to reopen link caches; always re-fetch links with issue_links to confirm the final state.

This server cannot be installed

A
license - permissive license
-
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
1wRelease cycle
21Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/VitalyOstanin/youtrack-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server