Which integrations are available for this server?

Provides comprehensive integration with [JetBrains](/mcp/servers/integrations/jetbrains) YouTrack 2025.2, enabling AI assistants to manage issues, sprints, dependencies, time tracking, knowledge base articles, agile boards, and analytics including Gantt charts and critical path analysis.

YouTrack MCP Server

License: MIT TypeScript MCP API

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

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

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 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 MCP Server

YouTrack MCP Server

Table of Contents

Quick Start

Highlights

Environment & Configuration

MCP Client Integration

Tool Catalog Summary

Architecture

Development

Troubleshooting

Quick Fixes

Security & Permissions

Contributing

License

Acknowledgements

Resources

New MCP Servers

Latest Blog Posts

MCP directory API