YouTrack MCP Server

Enterprise‑grade MCP server for JetBrains YouTrack 2025.2 giving AI assistants (Claude, VSCode MCP extensions, Continue.dev, Cline, Zed, custom connectors) safe, tool-based access to issues, sprints, dependencies (Gantt + critical path), time tracking and knowledge base content. Fully validated against official OpenAPI specification.

Quick Start
Highlights
What's New
Environment & Configuration
MCP Client Integration
Usage Examples
Analytics (Gantt & Critical Path)
Tool Catalog Summary
Architecture
Development
Troubleshooting
Security & Permissions
Roadmap
Contributing
License

Quick Start

git clone https://github.com/itsalfredakku/youtrack-mcp.git
cd youtrack-mcp
npm install
cp .env.example .env      # set YOUTRACK_URL + YOUTRACK_TOKEN
npm run build
npm start                 # stdio MCP server

Remote (SSE) for hosted usage / ChatGPT custom connector:

npm run start:remote      # http://localhost:3001/mcp/sse

Health check:

curl http://localhost:3001/health

Highlights

Domain	Capabilities
Dynamic Configuration	🆕 Auto-loads custom field values (State, Priority, Type) from YOUR YouTrack instance on startup - no more hardcoded examples!
Issues	CRUD, comments, transitions, dependency links, estimation, count queries
Issue History	🆕 Activity tracking, audit trail, change history with filtering
Bulk Operations	🆕 Apply commands to multiple issues, silent execution, auto-completion
Search Enhancement	🆕 Query auto-completion, context-aware suggestions
Saved Queries	🆕 Create, manage, and share saved searches
Agile	Sprint create/manage, issue assignment, progress metrics
Knowledge Base	Article create/update/search, tagging, linkage
Projects	Discovery, metadata, field summaries
Analytics	Gantt generation, dependency routing, critical path
Time Tracking	Log work, time summaries, reporting hooks
Performance	TTL caching, structured logging, graceful fallbacks
Reliability	Consistent response envelope & error normalization
API Coverage	🆕 ~80% of YouTrack REST API (12 of 15 domain areas)
Code Quality	🆕 ESLint compliant, TypeScript strict mode, 100% CI passing
API Validation	🆕 Verified against official YouTrack OpenAPI 3.0.1 spec

🌟 New: Dynamic Configuration

The MCP server now automatically adapts to your YouTrack customization! On startup, it:

✅ Fetches your actual State values (e.g., "In Progress", "Code Review")
✅ Loads your Priority values (e.g., "Critical", "High", "Medium")
✅ Discovers your Issue Types (e.g., "Bug", "Feature", "Epic")
✅ Generates accurate query examples that work with YOUR setup

No more errors from AI assistants suggesting "state: Open" when your instance uses "state: In Progress"!

See Dynamic Configuration Documentation for details.

What's New

🎉 Production Ready (November 2025)

The YouTrack MCP Server has reached v1.0.0 production status with:

✅ 100% ESLint Compliant - All code quality checks passing (Nov 22, 2025)
✅ OpenAPI Validated - Verified against official YouTrack 2025.2 spec (Nov 22, 2025)
✅ Dynamic Configuration - Auto-loads YOUR field values on startup (Nov 19, 2025)
✅ Multi-Project Support - Secure project scoping (Nov 10, 2025)
✅ 80% API Coverage - 12 of 15 YouTrack domain areas implemented

Recent Fixes:

Fixed all 26 ESLint violations across test suites and API clients
Validated all endpoints against official OpenAPI 3.0.1 specification
Corrected URL format handling (server now adds /api automatically)
Resolved dynamic config loader field fetching with three-tier strategy

📄 Read Full Release Notes for detailed changelog and migration guide.

Environment & Configuration

Minimal .env:

YOUTRACK_URL=https://your-instance.youtrack.cloud
YOUTRACK_TOKEN=your-permanent-token
PROJECT_ID=PROJECT-1
LOG_LEVEL=info
CACHE_ENABLED=true
CACHE_TTL=300000
ENABLE_WEBHOOKS=false
WEBHOOK_PORT=3000
WEBHOOK_SECRET=

Variable	Required	Description	Default
`YOUTRACK_URL`	✅	Base URL without `/api` suffix (e.g., `https://instance.youtrack.cloud`)	—
`YOUTRACK_TOKEN`	✅	Permanent token (Profile → Tokens)	—
`PROJECT_ID`	—	Default project shortName	—
`LOG_LEVEL`	—	error/warn/info/debug	info
`CACHE_ENABLED`	—	Enable in‑memory cache	true
`CACHE_TTL`	—	Cache TTL ms	300000
`ENABLE_WEBHOOKS`	—	Start webhook listener	false
`WEBHOOK_PORT`	—	Webhook port	3000
`WEBHOOK_SECRET`	—	HMAC secret	—

MCP Client Integration

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{ 
  "mcpServers": { 
    "youtrack": {
      "command": "node", 
      "args": ["/abs/path/youtrack-mcp/dist/index.js"], 
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud", 
        "YOUTRACK_TOKEN": "token",
        "PROJECT_ID": "PRJ"  // Optional
      } 
    } 
  } 
}

VSCode (.vscode/settings.json):

{ 
  "servers": { 
    "youtrack": { 
      "command": "node", 
      "args": ["./dist/index.js"], 
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud", 
        "YOUTRACK_TOKEN": "token",
      } 
    } 
  } 
}

Github Coding Agent:

 "mcpServers": {
    "youtrack": {      
       "type": "sse",
        "url": "https://your-instance.youtrack.cloud/mcp/sse",
        "headers": {
            "Authorization": "Bearer <your-token>"
            },
      "tools": [
        "issues",
        "projects",
        "users"        
      ]
    }
}

Continue.dev (continue.json):

{ 
  "mcp": { 
    "servers": [
      { 
        "name": "youtrack", 
        "command": "node", 
        "args": ["/abs/youtrack-mcp/dist/index.js"], 
        "env": {
          "YOUTRACK_URL": "https://your-instance.youtrack.cloud", 
          "YOUTRACK_TOKEN": "token"
        } 
      }
    ] 
  } 
}

Cline / Generic:

{ 
  "mcpServers": { 
    "youtrack": { 
      "command": "node", 
      "args": ["/abs/youtrack-mcp/dist/index.js"], 
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud", 
        "YOUTRACK_TOKEN": "token"
      } 
    } 
  } 
}

Zed:

{ 
  "context_servers": { 
    "youtrack": { 
      "command": "node", 
      "args": ["/abs/youtrack-mcp/dist/index.js"], 
      "env": {
        "YOUTRACK_URL": "https://your-instance.youtrack.cloud", 
        "YOUTRACK_TOKEN": "token"
      } 
    } 
  } 
}

Local test:

YOUTRACK_URL=https://your-instance.youtrack.cloud \
YOUTRACK_TOKEN=token \
node dist/index.js

Pitfalls: absolute path, no trailing slash, full token copy, JSON env values are strings.

Tool Catalog Summary

17 MCP Tools covering 12 domain areas:

Category	Tools & Key Actions
Issues	`issues` - create, update, comment, search, query, count, state transitions
Issue History 🆕	`activities` - global/issue activity tracking, audit trail, paginated history
Bulk Operations 🆕	`commands` - apply commands to multiple issues, get suggestions, silent execution
Search 🆕	`search_assist` - query auto-completion, context-aware suggestions
Saved Searches 🆕	`saved_queries` - create, list, update, delete saved queries
Agile Boards	`agile_boards` - list boards/sprints, assign issues, track progress
Knowledge Base	`knowledge_base` - create/update articles, search, manage hierarchy
Projects	`projects` - list, get details, validate access, custom fields
Users & Groups	`users` - list/search users, groups, team management
Time Tracking	`time_tracking` - log work, get entries, reports
Analytics	`analytics` - Gantt charts, critical path, resource allocation
Custom Fields	`custom_fields` - manage fields, bundles, project fields
Comments	`comments` - add, update, delete issue comments
Subscriptions	`subscriptions` - manage notification preferences
Auth	`auth` - OAuth2 status, login, token validation

See Tool Reference for complete documentation.

Architecture

Clients (Claude / VSCode / Continue / Zed)
          │  MCP (stdio or SSE)
 ┌────────▼────────┐
 │  Orchestrator   │ registry, routing, validation
 └────────┬────────┘
          │ domain calls
 ┌────────▼────────┐
 │ Domain Clients  │ issues / projects / agile / kb / analytics / time
 └────────┬────────┘
          │ REST
 ┌────────▼────────┐
 │  YouTrack API   │
 └─────────────────┘

Traits: strong typing, graceful degradation, normalized errors, pluggable caching/logging.

Development

npm install
npm run dev          # watch
npm run lint         # eslint
npm run type-check   # types
npm test             # tests
npm run build        # dist output

Structure: src/index.ts (entry), src/api/domains (domain clients), src/tools.ts (tool registry), src/utils, src/logger.ts.

Troubleshooting

Quick Fixes

Symptom	Cause	Fix
401 Unauthorized	Missing scope / expired token	Regenerate token with required permissions
404 Not Found (double `/api/api`)	URL has `/api` suffix	Remove `/api` from `YOUTRACK_URL`
Project not found	Hidden / archived / wrong ID	Use internal ID or verify access
Empty analytics	No issues in project	Seed baseline issues
SSE disconnects	Proxy idle timeout	Enable keep-alive / tune LB
AI wrong field values	Dynamic config failed	Check token permissions, restart server
Empty search results	`PROJECT_ID` too restrictive	Remove or update `PROJECT_ID`

Configuration Checklist:

✅ Absolute path in MCP client config
✅ No trailing slash on YOUTRACK_URL
✅ No /api suffix on YOUTRACK_URL (server adds automatically)
✅ Full token with perm: prefix
✅ JSON env values are strings
✅ Token has required permissions

Debug Mode: Use LOG_LEVEL=debug for detailed inspection.

📖 Complete Troubleshooting Guide - Comprehensive solutions for all common issues.

Security & Permissions

Recommended token capabilities: Issues (R/W), Projects (Read), Knowledge Base (R/W), Agile/Sprints (R/W), Time Tracking (if applicable). Store tokens as environment secrets; never commit.

Contributing

Fork & branch (feature/x)
Implement + tests
npm run lint && npm run type-check
Open PR with rationale

License

Acknowledgements

JetBrains YouTrack • MCP community • TypeScript ecosystem

Feedback / ideas? Open an issue or discussion.

YouTrack