itsalfredakku/youtrack-mcp

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.

Table of Contents

1. Quick Start
2. Highlights
3. What's New
4. Environment & Configuration
5. MCP Client Integration
6. Usage Examples
7. Analytics (Gantt & Critical Path)
8. Tool Catalog Summary
9. Architecture
10. Development
11. Troubleshooting
12. Security & Permissions
13. Roadmap
14. Contributing
15. 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

🌟 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 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

📄 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=

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:

See 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

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.

📖 - 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

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

License

MIT © 2025

Acknowledgements

JetBrains YouTrack • MCP community • TypeScript ecosystem

Feedback / ideas? Open an issue or discussion.