FlowTruxFlowTrux/Docs
Docsmcp

YouTrack MCP Server

Read and analyze JetBrains YouTrack issues, activity history, and projects from workflows

The YouTrack MCP server integrates with JetBrains YouTrack for issue tracking. It is read-only: workflows can fetch issues, drill into a single issue's details, walk change history (great for cycle-time analysis), and list projects. It does not create or modify issues.

Setup

  1. Get a permanent API token from your YouTrack instance:
  • Go to your YouTrack profile > Account Security > Tokens > New token.
  • Copy the token. Permanent tokens start with perm: (older YouTrack) or perm- (2024+). A UI session token will not work.
  1. Go to Settings > MCP Servers > Add Server.
  2. Select YouTrack.
  3. Enter the configuration:
FieldRequiredDescription
baseUrlYesYour YouTrack instance URL (e.g., https://mycompany.youtrack.cloud)
apiKeyYesPermanent token from step 1
  1. Click Save.

Token and URL gotchas

  • Same instance: a token is keyed to the instance that issued it. A token created on cloud (*.youtrack.cloud) does not work against a self-hosted server, and vice versa - issue the token on the same instance the baseUrl points to.
  • Self-hosted path prefix: self-hosted YouTrack often runs under a path, e.g. https://your-server/youtrack. Include that path in baseUrl - omitting it sends requests to the server root and you'll get login-page HTML instead of API responses.
  • Use HTTPS directly: an HTTP → HTTPS redirect drops the authorization header. Configure the final HTTPS URL.

Tools

get_issues

Fetch issues with an optional search query.

ParameterTypeRequiredDescription
querystringNoYouTrack search query (e.g., State: Open, project: MYPROJ)
fieldsstringNoComma-separated fields to return (default: id,idReadable,summary,description,created,resolved,updated)
limitnumberNoMaximum issues to return (default: 100)
skipnumberNoNumber of issues to skip, for pagination (default: 0)

Returns an array of issue records. created / resolved / updated are Unix millisecond timestamps; resolved is null while the issue is open.

get_issue

Get a single issue by ID with full details, including custom fields (State, Priority, Assignee).

ParameterTypeRequiredDescription
issueIdstringYesIssue ID (e.g., PROJ-123)
fieldsstringNoComma-separated fields to return (default includes customFields(name,value(name,text)))

get_issue_activities

Get the activity / change history for one issue - status transitions, field updates - as records sorted oldest to newest.

ParameterTypeRequiredDescription
issueIdstringYesIssue ID (e.g., PROJ-123)
categoriesstringNoActivity categories to filter (e.g., IssueStateCategory,IssueCreatedCategory)
fieldsstringNoFields to return for activities

Each record carries timestamp, author, the changed field, and added / removed values - enough to reconstruct when an issue entered and left each state.

get_all_activities

Get activities across all issues in one call - useful for bulk cycle-time analysis over a time window.

ParameterTypeRequiredDescription
categoriesstringNoActivity categories to filter (default: state changes)
startnumberNoStart timestamp (Unix ms)
endnumberNoEnd timestamp (Unix ms)
limitnumberNoMaximum activities to return (default: 1000)

Same record shape as get_issue_activities, plus a target object (id, idReadable, summary) identifying which issue each activity belongs to.

get_projects

List all accessible projects.

ParameterTypeRequiredDescription
fieldsstringNoFields to return (default: id,name,shortName,description)

Use each project's shortName in query strings (e.g. project: PROJ).

Example Workflow

A weekly engineering digest:

  1. Trigger - Cron schedule (Monday 9am)
  2. Action - youtrack:get_issues with query State: Open to pull the open backlog
  3. Action - youtrack:get_all_activities over the past week for state changes
  4. Agent - Compute cycle times, flag issues stuck in one state, summarize what shipped
  5. Agent - Send the digest to Slack, tools: slack:send_formatted_report
← TwilioPDF Generator→