Servidor MCP YouTrack
Servidor MCP para YouTrack que oferece acesso via ferramentas para assistentes de IA gerenciarem issues, sprints, dependências, rastreamento de tempo e base de conhecimento.
Início Rápido```bash
git clone https://git.eloware.com.br/felipe.mendes/youtrack-mcp.git
cd youtrack-mcp
npm install
cp .env.example .env # configurar YOUTRACK_URL + YOUTRACK_TOKEN
npm run build
npm start # servidor MCP stdio
Remoto (SSE) para uso hospedado / conector customizado ChatGPT:```bash
npm run start:remote # http://localhost:3001/mcp/sse
Ambiente e Configuração
.env mínimo:```properties
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=
| Variável | Obrigatória | Descrição | Padrão |
| ----------------- | ----------- | ---------------------------------- | ------ |
| `YOUTRACK_URL` | ✅ | URL base (sem barra final) | — |
| `YOUTRACK_TOKEN` | ✅ | Token permanente (Perfil → Tokens) | — |
| `PROJECT_ID` | — | shortName do projeto padrão | — |
| `LOG_LEVEL` | — | error/warn/info/debug | info |
| `CACHE_ENABLED` | — | Habilitar cache em memória | true |
| `CACHE_TTL` | — | TTL do cache em ms | 300000 |
| `ENABLE_WEBHOOKS` | — | Iniciar listener de webhook | false |
| `WEBHOOK_PORT` | — | Porta do webhook | 3000 |
| `WEBHOOK_SECRET` | — | Segredo HMAC | — |
---
## Integração com Cliente MCP
Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):```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" // Opcional
}
}
}
}
VSCode (.vscode/settings.json):```json
{
"servers": {
"youtrack": {
"command": "node",
"args": ["./dist/index.js"],
"env": {
"YOUTRACK_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_TOKEN": "token"
}
}
}
}
Continue.dev (`continue.json`):```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:```json
{
"mcpServers": {
"youtrack": {
"command": "node",
"args": ["/abs/youtrack-mcp/dist/index.js"],
"env": {
"YOUTRACK_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_TOKEN": "token"
}
}
}
}
Zed:```json
{
"context_servers": {
"youtrack": {
"command": "node",
"args": ["/abs/youtrack-mcp/dist/index.js"],
"env": {
"YOUTRACK_URL": "https://your-instance.youtrack.cloud",
"YOUTRACK_TOKEN": "token"
}
}
}
}
Teste local:bash
YOUTRACK_URL=https://your-instance.youtrack.cloud \
YOUTRACK_TOKEN=token \
node dist/index.js
Importante: Use caminho absoluto, sem barra final na URL, token completo, valores env em JSON são strings.
Ferramentas Disponíveis
| Categoria | Ferramentas |
|---|---|
| Issues | create_issue, update_issue, add_issue_comment, search_issues |
| Estado | start_working_on_issue, change_issue_state, complete_issue |
| Agile | create_sprint, list_sprints, assign_issue_to_sprint |
| Conhecimento | create_article, update_article, search_articles |
| Projetos | list_projects, get_project_details |
| Análises | generate_gantt_chart, get_critical_path, create_issue_dependency |
| Tempo | log_work_item, get_time_report |
Solução de Problemas
- 401 Não Autorizado: Regenerar token com permissões necessárias
- Projeto não encontrado: Verificar ID ou acesso ao projeto
- Use
LOG_LEVEL=debugpara inspeção detalhada
Segurança
Permissões necessárias no token: Issues (R/W), Projetos (Leitura), Base de Conhecimento (R/W), Agile/Sprints (R/W)
⚠️ Nunca faça commit de tokens - use variáveis de ambiente
