Yandex Tracker

Servidor MCP do Yandex Tracker

mcp-name: io.github.aikts/yandex-tracker-mcp

Um servidor abrangente do Model Context Protocol (MCP) que permite que assistentes de IA interajam com as APIs do Yandex Tracker. Este servidor fornece acesso seguro e autenticado a issues, filas, comentários, apontamentos de horas e funcionalidade de busca do Yandex Tracker, com cache Redis opcional para melhor desempenho.

Documentação em russo está disponível aqui / Документация на русском языке доступна здесь.

Recursos

• Gerenciamento Completo de Filas: Liste e acesse todas as filas disponíveis do Yandex Tracker com suporte a paginação, recuperação de tags e metadados detalhados
• Projetos, Portfólios e Metas: Ferramentas dedicadas de leitura e escrita com esquemas explícitos para cada tipo de entidade na API "entities" do Tracker (opt-in via TRACKER_ENTITIES_ENABLED)
• Gerenciamento de Usuários: Recupere informações de contas de usuário, incluindo detalhes de login, endereços de e-mail, status de licença e dados organizacionais
• Ciclo de Vida Completo de Issues: Crie, leia, atualize e gerencie issues com suporte a campos personalizados, anexos e transições de fluxo de trabalho
• Gerenciamento de Fluxo de Trabalho de Status: Execute transições de status, feche issues com resoluções e navegue por fluxos de trabalho complexos
• Gerenciamento de Campos: Acesse campos globais, campos locais específicos de filas, status, tipos de issue, prioridades e resoluções
• Quadros e Sprints: Liste quadros ágeis e seus sprints para encontrar IDs de sprint para planejamento de issues
• Linguagem de Consulta Avançada: Suporte completo à Linguagem de Consulta do Yandex Tracker com filtragem complexa, ordenação e funções de data
• Cache de Desempenho: Camada de cache Redis opcional para melhorar os tempos de resposta
• Controles de Segurança: Restrições configuráveis de acesso a filas e manipulação segura de tokens
• Múltiplas Opções de Transporte: Suporte para transportes stdio, SSE (obsoleto) e HTTP para integração flexível
• Autenticação OAuth 2.0: Autenticação dinâmica baseada em token com suporte a renovação automática como alternativa aos tokens de API estáticos
• Suporte a Organizações: Compatível com IDs de organização padrão e de nuvem

Configuração do ID da Organização

Escolha uma das opções a seguir com base no seu tipo de organização Yandex:

• Organização Yandex Cloud: Use a variável de ambiente TRACKER_CLOUD_ORG_ID posteriormente para organizações gerenciadas pelo Yandex Cloud
• Organização Yandex 360: Use a variável de ambiente TRACKER_ORG_ID posteriormente para organizações Yandex 360

Você pode encontrar o ID da sua organização na URL do Yandex Tracker ou nas configurações da organização.

Configuração do Cliente MCP

Instalando a extensão no Claude Desktop

O Servidor MCP do Yandex Tracker pode ser instalado com um clique no Claude Desktop como uma extensão.

Instalação

1. Baixe o arquivo *.mcpb dos Lançamentos do GitHub.
2. Clique duas vezes no arquivo baixado para instalá-lo no Claude Desktop.
3. Forneça seu token OAuth do Yandex Tracker quando solicitado.
4. Certifique-se de que a extensão esteja habilitada - agora você pode usar este Servidor MCP.

Instalação manual

Pré-requisitos

• uv instalado globalmente
• Token de API válido do Yandex Tracker com as permissões apropriadas

As seções a seguir mostram como configurar o servidor MCP para diferentes clientes de IA. Você pode usar uvx yandex-tracker-mcp@latest ou a imagem Docker ghcr.io/aikts/yandex-tracker-mcp:latest. Ambos exigem estas variáveis de ambiente:

• Autenticação (uma das seguintes):
  • TRACKER_TOKEN - Seu token OAuth do Yandex Tracker
  • TRACKER_IAM_TOKEN - Seu token IAM
  • TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY - Credenciais da conta de serviço
• Organização - exatamente uma das seguintes:
  • TRACKER_CLOUD_ORG_ID - Seu ID de organização Yandex Cloud
  • TRACKER_ORG_ID - Seu ID de organização Yandex 360

Defina uma das duas. Definir ambas faz com que toda chamada ao Tracker falhe com Only one of org_id or cloud_org_id should be provided. Os exemplos abaixo usam TRACKER_CLOUD_ORG_ID; no Yandex 360, substitua essa chave por TRACKER_ORG_ID.

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

claude mcp add yandex-tracker uvx yandex-tracker-mcp@latest \
  -e TRACKER_TOKEN=your_tracker_token_here \
  -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here \
  -e TRANSPORT=stdio

claude mcp add yandex-tracker docker "run --rm -i -e TRACKER_TOKEN=your_tracker_token_here -e TRACKER_CLOUD_ORG_ID=your_cloud_org_id_here -e TRANSPORT=stdio ghcr.io/aikts/yandex-tracker-mcp:latest"

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "context_servers": {
    "yandex-tracker": {
      "source": "custom",
      "command": {
        "path": "uvx",
        "args": ["yandex-tracker-mcp@latest"],
        "env": {
          "TRACKER_TOKEN": "your_tracker_token_here",
          "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
        }
      }
    }
  }
}

{
  "context_servers": {
    "yandex-tracker": {
      "source": "custom",
      "command": {
        "path": "docker",
        "args": [
          "run", "--rm", "-i",
          "-e", "TRACKER_TOKEN",
          "-e", "TRACKER_CLOUD_ORG_ID",
          "ghcr.io/aikts/yandex-tracker-mcp:latest"
        ],
        "env": {
          "TRACKER_TOKEN": "your_tracker_token_here",
          "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
        }
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tracker-token",
      "description": "Yandex Tracker Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "cloud-org-id",
      "description": "Yandex Cloud Organization ID"
    }
  ],
  "servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "${input:tracker-token}",
        "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
        "TRANSPORT": "stdio"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "tracker-token",
      "description": "Yandex Tracker Token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "cloud-org-id",
      "description": "Yandex Cloud Organization ID"
    }
  ],
  "servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "${input:tracker-token}",
        "TRACKER_CLOUD_ORG_ID": "${input:cloud-org-id}",
        "TRANSPORT": "stdio"
      }
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "yandex-tracker": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "uvx",
      "args": ["yandex-tracker-mcp@latest"],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

{
  "mcpServers": {
    "yandex-tracker": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "TRACKER_TOKEN",
        "-e", "TRACKER_CLOUD_ORG_ID",
        "ghcr.io/aikts/yandex-tracker-mcp:latest"
      ],
      "env": {
        "TRACKER_TOKEN": "your_tracker_token_here",
        "TRACKER_CLOUD_ORG_ID": "your_cloud_org_id_here"
      }
    }
  }
}

Notas Importantes:

• Substitua os valores de exemplo pelas suas credenciais reais
• Reinicie seu cliente de IA após alterações de configuração
• Certifique-se de que uvx esteja instalado e disponível no PATH do seu sistema
• Para uso em produção, considere usar variáveis de ambiente em vez de codificar tokens

Ferramentas MCP Disponíveis

O servidor expõe as seguintes ferramentas através do protocolo MCP:

Transporte http

O servidor MCP também pode ser executado no modo streamable-http para integrações baseadas na web ou quando o transporte stdio não é adequado.

Variáveis de Ambiente do Modo streamable-http

# Required - Set transport to streamable-http mode
TRANSPORT=streamable-http

# Server Configuration
HOST=0.0.0.0  # Default: 0.0.0.0 (all interfaces)
PORT=8000     # Default: 8000

Iniciando o Servidor streamable-http

# Basic streamable-http server startup
TRANSPORT=streamable-http uvx yandex-tracker-mcp@latest

# With custom host and port
TRANSPORT=streamable-http \
HOST=localhost \
PORT=9000 \
uvx yandex-tracker-mcp@latest

# With all environment variables
TRANSPORT=streamable-http \
HOST=0.0.0.0 \
PORT=8000 \
TRACKER_TOKEN=your_token \
TRACKER_CLOUD_ORG_ID=your_org_id \
uvx yandex-tracker-mcp@latest

Você pode pular a configuração de TRACKER_CLOUD_ORG_ID ou TRACKER_ORG_ID se estiver usando o seguinte formato ao conectar ao Servidor MCP (exemplo para Claude Code):

claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?cloudOrgId=your_cloud_org_id&"

ou

claude mcp add --transport http yandex-tracker "http://localhost:8000/mcp/?orgId=org_id&"

Você também pode pular a configuração da variável de ambiente global TRACKER_TOKEN se optar por usar autenticação OAuth 2.0 (veja abaixo).

Autenticação OAuth 2.0

O Servidor MCP do Yandex Tracker suporta autenticação OAuth 2.0 como uma alternativa segura aos tokens de API estáticos. Quando configurado, o servidor atua como um provedor OAuth, facilitando a autenticação entre seu cliente MCP e os serviços OAuth do Yandex.

Como o OAuth Funciona

O servidor MCP implementa um fluxo padrão de código de autorização OAuth 2.0:

1. Registro do Cliente: Seu cliente MCP se registra no servidor para obter credenciais de cliente
2. Autorização: Os usuários são redirecionados ao OAuth do Yandex para autenticar
3. Troca de Token: O servidor troca códigos de autorização por tokens de acesso
4. Acesso à API: Os clientes usam tokens de portador para todas as solicitações de API
5. Atualização de Token: Tokens expirados podem ser atualizados sem reautenticação

MCP Client → MCP Server → Yandex OAuth → User Authentication
    ↑                                           ↓
    └────────── Access Token ←─────────────────┘

Configuração do OAuth

Para habilitar a autenticação OAuth, defina as seguintes variáveis de ambiente:

# Enable OAuth mode
OAUTH_ENABLED=true

# Yandex OAuth Application Credentials (required for OAuth)
OAUTH_CLIENT_ID=your_yandex_oauth_app_id
OAUTH_CLIENT_SECRET=your_yandex_oauth_app_secret

# Public URL of your MCP server (required for OAuth callbacks)
MCP_SERVER_PUBLIC_URL=https://your-mcp-server.example.com

# Optional OAuth settings
OAUTH_SERVER_URL=https://oauth.yandex.ru  # Default Yandex OAuth server

# When OAuth is enabled, TRACKER_TOKEN becomes optional

Escopos do OAuth

Com OAUTH_USE_SCOPES=true (o padrão), o servidor solicita, anuncia e exige os escopos do Yandex Tracker tracker:read e tracker:write — ou tracker:read sozinho quando TRACKER_READ_ONLY=true, para que uma instância somente leitura nunca peça ao usuário acesso de escrita. Definir OAUTH_USE_SCOPES=false remove os escopos do fluxo completamente, que é o que a federação do Yandex Cloud exige.

Configurando um Aplicativo OAuth do Yandex

1. Vá para Yandex OAuth e crie um novo aplicativo
2. Defina a URL de retorno de chamada para: {MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback
3. Solicite as seguintes permissões:
   • tracker:read — Permissões de leitura para o Tracker
   • tracker:write — Permissões de escrita para o Tracker
4. Salve seu ID de Cliente e Segredo de Cliente

OAuth vs Autenticação por Token Estático

Limitações do Modo OAuth

• Atualmente, o modo OAuth exige que o servidor MCP seja publicamente acessível para URLs de retorno de chamada
• O modo OAuth é mais adequado para clientes interativos que suportam fluxos de autenticação baseados na web

Usando OAuth com Clientes MCP

Quando o OAuth está habilitado, os clientes MCP precisarão:

1. Suportar o fluxo de código de autorização OAuth 2.0
2. Lidar com a atualização de tokens quando os tokens de acesso expirarem
3. Armazenar tokens de atualização com segurança para autenticação persistente

Nota: Nem todos os clientes MCP atualmente suportam autenticação OAuth. Verifique a documentação do seu cliente para compatibilidade com OAuth.

Exemplo de configuração para Claude Code:

claude mcp add --transport http yandex-tracker https://your-mcp-server.example.com/mcp/ -s user

Armazenamento de Dados OAuth

O servidor MCP suporta dois backends de armazenamento diferentes para dados OAuth (registros de clientes, tokens de acesso, tokens de atualização e estados de autorização):

Armazenamento em Memória (Padrão)

O armazenamento em memória mantém todos os dados OAuth na memória do servidor. Esta é a opção padrão e não requer configuração adicional.

Características:

• Persistência: Os dados são perdidos quando o servidor reinicia
• Desempenho: Acesso muito rápido, pois os dados são armazenados em memória
• Escalabilidade: Limitado a uma única instância do servidor
• Configuração: Nenhuma dependência adicional necessária
• Melhor para: Desenvolvimento, testes ou implantações de instância única onde perder sessões OAuth na reinicialização é aceitável

Configuração:

OAUTH_STORE=memory  # Default value, can be omitted

Armazenamento Redis

O armazenamento Redis fornece armazenamento persistente para dados OAuth usando um banco de dados Redis. Isso garante que as sessões OAuth sobrevivam a reinicializações do servidor e permite implantações de múltiplas instâncias.

Características:

• Persistência: Os dados persistem entre reinicializações do servidor
• Desempenho: Acesso rápido com sobrecarga de rede
• Escalabilidade: Suporta múltiplas instâncias do servidor compartilhando o mesmo banco de dados Redis
• Configuração: Requer instalação e configuração do servidor Redis
• Melhor para: Implantações de produção, configurações de alta disponibilidade ou quando as sessões OAuth devem persistir

Configuração:

# Enable Redis store for OAuth data
OAUTH_STORE=redis

# Redis connection settings (same as used for tools caching)
REDIS_ENDPOINT=localhost                  # Default: localhost
REDIS_PORT=6379                           # Default: 6379
REDIS_DB=0                                # Default: 0
REDIS_PASSWORD=your_redis_password        # Optional: Redis password
REDIS_POOL_MAX_SIZE=10                    # Default: 10

Comportamento de Armazenamento:

• Informações do Cliente: Armazenadas persistentemente
• Estados OAuth: Armazenados com TTL (tempo de vida) por segurança
• Códigos de Autorização: Armazenados com TTL e limpos automaticamente após o uso
• Tokens de Acesso: Armazenados com expiração automática com base no tempo de vida do token
• Tokens de Atualização: Armazenados persistentemente até serem revogados
• Namespacing de Chaves: Usa prefixos oauth:* para evitar conflitos com outros dados Redis

Criptografia de Token (Obrigatória para Armazenamento Redis)

Ao usar o armazenamento Redis, você deve configurar a criptografia para proteger os tokens OAuth em repouso. Os valores dos tokens são criptografados usando Fernet (AES-128) e as chaves Redis usam hashes SHA-256 em vez de tokens brutos, evitando a exposição de tokens se o Redis for comprometido.

Gere uma chave de criptografia:

python3 -c "import base64, os; print(base64.b64encode(os.urandom(32)).decode())"

Configuração:

# Single encryption key
OAUTH_ENCRYPTION_KEYS=<base64-encoded-32-byte-key>

# Multiple keys for rotation (first encrypts, all decrypt)
OAUTH_ENCRYPTION_KEYS=<new-key>,<old-key>

A rotação de chaves permite atualizações contínuas de chaves: adicione a nova chave primeiro, aguarde os tokens antigos expirarem e remova a chave antiga.

Notas Importantes:

• Ambos os armazenamentos usam as mesmas configurações de conexão Redis que o sistema de cache de ferramentas
• Ao usar o armazenamento Redis, certifique-se de que sua instância Redis esteja devidamente protegida e acessível
• A configuração OAUTH_STORE afeta apenas o armazenamento de dados OAuth; o cache de ferramentas usa TOOLS_CACHE_ENABLED
• O armazenamento Redis usa serialização JSON para melhor compatibilidade entre linguagens e depuração

Autenticação

O Servidor MCP do Yandex Tracker suporta múltiplos métodos de autenticação com uma ordem clara de prioridade. O servidor usará o primeiro método de autenticação disponível com base nesta hierarquia:

Ordem de Prioridade de Autenticação

1. Token OAuth Dinâmico (maior prioridade)

   • Quando o OAuth está habilitado e um usuário autentica via fluxo OAuth
   • Os tokens são obtidos dinamicamente e atualizados por sessão de usuário
   • Suporta tanto o OAuth padrão do Yandex quanto o OAuth federativo do Yandex Cloud
   • Variáveis de ambiente necessárias: OAUTH_ENABLED=true, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, MCP_SERVER_PUBLIC_URL
   • Variáveis adicionais para OAuth federativo: OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth, OAUTH_TOKEN_TYPE=Bearer, OAUTH_USE_SCOPES=false

2. Token OAuth de Portador de Passagem

   • Quando o middleware MCP OAuth não fornece um token, o servidor pode ler um token OAuth do Yandex do cabeçalho Authorization: Bearer <token> de entrada
   • Útil atrás de um proxy reverso ou gateway confiável que autentica usuários, resolve seu token OAuth do Yandex armazenado e o injeta por solicitação
   • O token do MCP OAuth ainda tem prioridade quando o modo OAuth está habilitado e ativo

3. Token OAuth Estático

   • Token OAuth tradicional fornecido via variável de ambiente
   • Token único usado para todas as solicitações
   • Variável de ambiente necessária: TRACKER_TOKEN (seu token OAuth)

4. Token IAM Estático

   • Token IAM (Identity and Access Management) para autenticação serviço a serviço
   • Adequado para sistemas automatizados e pipelines de CI/CD
   • Variável de ambiente necessária: TRACKER_IAM_TOKEN (seu token IAM)

5. Token IAM Dinâmico (menor prioridade)

   • Obtido automaticamente usando credenciais de conta de serviço
   • O token é buscado e atualizado automaticamente
   • Variáveis de ambiente necessárias: TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY

Cenários de Autenticação

Cenário 1: OAuth com Tokens Dinâmicos (Recomendado para Uso Interativo)

# Enable OAuth mode
OAUTH_ENABLED=true
OAUTH_CLIENT_ID=your_oauth_app_id
OAUTH_CLIENT_SECRET=your_oauth_app_secret
MCP_SERVER_PUBLIC_URL=https://your-server.com

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

Cenário 2: Token OAuth Estático (Configuração Simples)

# OAuth token
TRACKER_TOKEN=your_oauth_token

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

Cenário 3: Token de Portador de Passagem Atrás de um Proxy Reverso

Use este modo quando um gateway confiável lida com a autenticação do usuário, consulta o token OAuth do Yandex do usuário e encaminha a solicitação ao servidor MCP com esse token no cabeçalho da solicitação:

Authorization: Bearer <user_yandex_oauth_token>

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

Este token de passagem é usado apenas quando o middleware MCP OAuth não forneceu um token de acesso para a solicitação. Em implantações com OAuth habilitado e uma sessão MCP OAuth ativa, o token MCP OAuth tem prioridade.

Cenário 4: Token IAM Estático

# IAM token
TRACKER_IAM_TOKEN=your_iam_token

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

Cenário 5: Token IAM Dinâmico com Conta de Serviço

# Service account credentials
TRACKER_SA_KEY_ID=your_key_id
TRACKER_SA_SERVICE_ACCOUNT_ID=your_service_account_id
TRACKER_SA_PRIVATE_KEY=your_private_key

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

Cenário 6: OAuth Federativo para Aplicações OIDC (Avançado)

# Enable OAuth with Yandex Cloud federation
OAUTH_ENABLED=true
OAUTH_SERVER_URL=https://auth.yandex.cloud/oauth
OAUTH_TOKEN_TYPE=Bearer
OAUTH_USE_SCOPES=false
OAUTH_CLIENT_ID=your_oidc_client_id
OAUTH_CLIENT_SECRET=your_oidc_client_secret
MCP_SERVER_PUBLIC_URL=https://your-server.com

# Organization ID (choose one)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id  # or TRACKER_ORG_ID

Esta configuração permite a autenticação por meio de aplicações OIDC do Yandex Cloud, que é necessária para contas federadas no Yandex Cloud. Usuários federados autenticam por meio do provedor de identidade (IdP) da sua organização e usam este fluxo OAuth para acessar as APIs do Yandex Tracker.

Notas Importantes

• O servidor verifica os métodos de autenticação na ordem listada acima
• Apenas um método de autenticação será usado por vez
• Para uso em produção, tokens dinâmicos (OAuth ou IAM) são recomendados para melhor segurança
• Tokens IAM têm vida útil mais curta que tokens OAuth e podem precisar de renovação mais frequente
• Ao usar contas de serviço, garanta que a conta tenha permissões apropriadas para o Yandex Tracker

Configuração

Variáveis de Ambiente

# Authentication (use one of the following methods)
# Method 1: OAuth Token
TRACKER_TOKEN=your_yandex_tracker_oauth_token

# Method 2: IAM Token
TRACKER_IAM_TOKEN=your_iam_token

# Method 3: Service Account (for dynamic IAM token)
TRACKER_SA_KEY_ID=your_key_id                    # Service account key ID
TRACKER_SA_SERVICE_ACCOUNT_ID=your_sa_id        # Service account ID
TRACKER_SA_PRIVATE_KEY=your_private_key          # Service account private key

# Organization Configuration (set exactly one - setting both is an error)
TRACKER_CLOUD_ORG_ID=your_cloud_org_id    # For Yandex Cloud organizations
TRACKER_ORG_ID=your_org_id                # For Yandex 360 organizations

# API Configuration (optional)
TRACKER_API_BASE_URL=https://api.tracker.yandex.net  # Default: https://api.tracker.yandex.net
TRACKER_API_TIMEOUT=10                    # Default: 10 - Per-request timeout in seconds for Tracker API calls

# Security - Restrict access to specific queues (optional)
TRACKER_LIMIT_QUEUES=PROJ1,PROJ2,DEV      # Comma-separated queue keys - allow-list of accessible queues
TRACKER_READ_ONLY_QUEUES=PROJ2            # Comma-separated queue keys - allowed for reads but reject writes (per-queue read-only)
TRACKER_ENTITIES_ENABLED=true             # Default: false - Register project/portfolio/goal tools (NOT covered by the queue restrictions above)

# Server Configuration
HOST=0.0.0.0                              # Default: 0.0.0.0
PORT=8000                                 # Default: 8000
TRANSPORT=stdio                           # Options: stdio, streamable-http, sse

# Redis connection settings (used for caching and OAuth store)
REDIS_ENDPOINT=localhost                  # Default: localhost
REDIS_PORT=6379                           # Default: 6379
REDIS_DB=0                                # Default: 0
REDIS_PASSWORD=your_redis_password        # Optional: Redis password
REDIS_POOL_MAX_SIZE=10                    # Default: 10

# Tools caching configuration (optional)
TOOLS_CACHE_ENABLED=true                  # Default: false
TOOLS_CACHE_REDIS_TTL=3600                # Default: 3600 seconds (1 hour)

# OAuth 2.0 Authentication (optional)
OAUTH_ENABLED=true                        # Default: false
OAUTH_STORE=redis                         # Options: memory, redis (default: memory)
OAUTH_SERVER_URL=https://oauth.yandex.ru  # Default: https://oauth.yandex.ru (use https://auth.yandex.cloud/oauth for federation)
OAUTH_TOKEN_TYPE=<Bearer|OAuth|<empty>>   # Default: <empty> (required to be Bearer for Yandex Cloud federation)
OAUTH_USE_SCOPES=true                     # Default: true (set to false for Yandex Cloud federation)
OAUTH_CLIENT_ID=your_oauth_client_id      # Required when OAuth enabled
OAUTH_CLIENT_SECRET=your_oauth_secret     # Required when OAuth enabled
MCP_SERVER_PUBLIC_URL=https://your.server.com  # Required when OAuth enabled
TRACKER_READ_ONLY=true                    # Default: false - Disable all write tools for the whole instance

Controle de Acesso a Filas

O acesso a filas pode ser definido em três níveis, do mais amplo ao mais granular:

• TRACKER_LIMIT_QUEUES — lista de permissão de chaves de fila. Filas fora da lista são tratadas como não encontradas / não permitidas tanto para leituras quanto para escritas. As chaves são comparadas ignorando maiúsculas/minúsculas, aqui e em TRACKER_READ_ONLY_QUEUES, então dev e DEV nomeiam a mesma fila. A única exceção são as ferramentas de quadro: um quadro pertence à organização em vez de a uma fila, então elas não são filtradas e podem nomear uma fila restrita nas configurações de um quadro.
• TRACKER_READ_ONLY — quando true, todas as ferramentas de escrita são desregistradas, então toda a instância fica somente leitura.
• TRACKER_READ_ONLY_QUEUES — lista de permissão somente leitura por fila. Ferramentas de escrita permanecem registradas, mas qualquer chamada de mutação (criar/atualizar/mover/comentar/ registro de trabalho/vínculo, criação de versão de fila) direcionada a uma fila listada é rejeitada, enquanto leituras continuam funcionando. Filas não listadas aqui permanecem leitura-escrita.

Ferramentas de projeto/portfólio/objetivo estão fora deste modelo. Um projeto, portfólio ou objetivo não é mapeável de forma confiável para uma única fila, então nenhuma das três configurações acima os restringe — nem as ferramentas de leitura (project_get, project_find, *_get_comments, …) nem as ferramentas de escrita (incluindo ferramentas de comentário e checklist). Habilitá-las concede acesso organizacional amplo a essas entidades para qualquer pessoa que possa alcançar o servidor. Por esse motivo, elas são opt-in: são registradas apenas quando TRACKER_ENTITIES_ENABLED=true (padrão false), o que também mantém o manifesto de ferramentas pequeno para implantações que não precisam delas. TRACKER_READ_ONLY ainda se aplica: ele desregistra ferramentas de escrita de entidades junto com todas as outras ferramentas de escrita.

Isso permite que uma única instância seja leitura-escrita em algumas filas e somente leitura em outras ao mesmo tempo — por exemplo, TRACKER_LIMIT_QUEUES=DEV,MGMT junto com TRACKER_READ_ONLY_QUEUES=MGMT dá acesso total a DEV e visibilidade somente leitura em MGMT. Isso é especialmente útil para um gateway MCP compartilhado onde usuários finais alcançam o Tracker apenas pelo servidor e nunca seguram o token bruto eles mesmos.

Essas verificações são proteções em processo. Para clientes que seguram o token bruto do Tracker diretamente, limites reais devem ser adicionalmente aplicados no próprio token.

Implantação com Docker

Usando Imagem Pré-construída (Recomendado)

A imagem usa por padrão TRANSPORT=stdio, que se comunica pelo stdin/stdout do contêiner e não abre porta. Defina TRANSPORT=streamable-http para os exemplos abaixo, onde o servidor é alcançado por HTTP; para um cliente stdio, execute o contêiner com -i e sem -p em vez disso (veja os exemplos de Configuração de Cliente MCP).

# Using environment file (it must set TRANSPORT=streamable-http)
docker run --env-file .env -p 8000:8000 ghcr.io/aikts/yandex-tracker-mcp:latest

# With inline environment variables
docker run -e TRACKER_TOKEN=your_token \
           -e TRACKER_CLOUD_ORG_ID=your_org_id \
           -e TRANSPORT=streamable-http \
           -p 8000:8000 \
           ghcr.io/aikts/yandex-tracker-mcp:latest

Construindo a Imagem Localmente

docker build -t yandex-tracker-mcp .

Docker Compose

Usando imagem pré-construída:

services:
  mcp-tracker:
    image: ghcr.io/aikts/yandex-tracker-mcp:latest
    ports:
      - "8000:8000"
    environment:
      - TRACKER_TOKEN=${TRACKER_TOKEN}
      - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
      - TRANSPORT=streamable-http

Construindo localmente:

services:
  mcp-tracker:
    build: .
    ports:
      - "8000:8000"
    environment:
      - TRACKER_TOKEN=${TRACKER_TOKEN}
      - TRACKER_CLOUD_ORG_ID=${TRACKER_CLOUD_ORG_ID}
      - TRANSPORT=streamable-http

Configuração de Desenvolvimento

# Clone and setup
git clone https://github.com/aikts/yandex-tracker-mcp
cd yandex-tracker-mcp

# Install development dependencies
uv sync --dev

# Formatting and static checking
task

Licença

Este projeto é licenciado sob os termos especificados no arquivo LICENSE.

Suporte

Para problemas e perguntas:

• Revise a documentação da API do Yandex Tracker
• Envie problemas em https://github.com/aikts/yandex-tracker-mcp/issues