Yandex Tracker

Servidor MCP de Yandex Tracker

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

Un servidor integral del Protocolo de Contexto de Modelos (MCP) que permite a los asistentes de IA interactuar con las APIs de Yandex Tracker. Este servidor proporciona acceso seguro y autenticado a issues, colas, comentarios, registros de trabajo y funcionalidad de búsqueda de Yandex Tracker, con caché opcional de Redis para mejorar el rendimiento.

La documentación en ruso está disponible aquí / Documentation in English is available here.

Características

• Gestión completa de colas: Lista y accede a todas las colas disponibles de Yandex Tracker con soporte de paginación, recuperación de etiquetas y metadatos detallados
• Proyectos, Portafolios y Objetivos: Herramientas dedicadas de lectura y escritura con esquemas explícitos para cada tipo de entidad en la API de "entidades" de Tracker (opt-in mediante TRACKER_ENTITIES_ENABLED)
• Gestión de usuarios: Recupera información de cuentas de usuario, incluidos detalles de inicio de sesión, direcciones de correo electrónico, estado de licencia y datos organizativos
• Ciclo de vida completo de issues: Crea, lee, actualiza y gestiona issues con soporte para campos personalizados, archivos adjuntos y transiciones de flujo de trabajo
• Gestión de flujos de trabajo de estado: Ejecuta transiciones de estado, cierra issues con resoluciones y navega por flujos de trabajo complejos
• Gestión de campos: Accede a campos globales, campos locales específicos de cola, estados, tipos de issue, prioridades y resoluciones
• Tableros y sprints: Lista tableros ágiles y sus sprints para encontrar IDs de sprint para la planificación de issues
• Lenguaje de consulta avanzado: Soporte completo del Lenguaje de Consulta de Yandex Tracker con filtrado complejo, ordenamiento y funciones de fecha
• Caché de rendimiento: Capa de caché opcional de Redis para mejorar los tiempos de respuesta
• Controles de seguridad: Restricciones configurables de acceso a colas y manejo seguro de tokens
• Múltiples opciones de transporte: Soporte para transportes stdio, SSE (obsoleto) y HTTP para una integración flexible
• Autenticación OAuth 2.0: Autenticación dinámica basada en tokens con soporte de renovación automática como alternativa a los tokens API estáticos
• Soporte de organizaciones: Compatible con IDs de organizaciones estándar y de nube

Configuración del ID de organización

Elige una de las siguientes opciones según tu tipo de organización de Yandex:

• Organización de Yandex Cloud: Usa la variable de entorno TRACKER_CLOUD_ORG_ID más adelante para organizaciones gestionadas por Yandex Cloud
• Organización de Yandex 360: Usa la variable de entorno TRACKER_ORG_ID más adelante para organizaciones de Yandex 360

Puedes encontrar tu ID de organización en la URL de Yandex Tracker o en la configuración de la organización.

Configuración del cliente MCP

Instalación de la extensión en Claude Desktop

El Servidor MCP de Yandex Tracker se puede instalar con un clic en Claude Desktop como extensión.

Instalación

1. Descarga el archivo *.mcpb desde GitHub Releases.
2. Haz doble clic en el archivo descargado para instalarlo en Claude Desktop.
3. Proporciona tu token OAuth de Yandex Tracker cuando se te solicite.
4. Asegúrate de que la extensión esté habilitada: ahora puedes usar este Servidor MCP.

Instalación manual

Requisitos previos

• uv instalado globalmente
• Token API válido de Yandex Tracker con los permisos adecuados

Las siguientes secciones muestran cómo configurar el servidor MCP para diferentes clientes de IA. Puedes usar uvx yandex-tracker-mcp@latest o la imagen de Docker ghcr.io/aikts/yandex-tracker-mcp:latest. Ambos requieren estas variables de entorno:

• Autenticación (una de las siguientes):
  • TRACKER_TOKEN - Tu token OAuth de Yandex Tracker
  • TRACKER_IAM_TOKEN - Tu token IAM
  • TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY - Credenciales de cuenta de servicio
• Organización - exactamente una de las siguientes:
  • TRACKER_CLOUD_ORG_ID - Tu ID de organización de Yandex Cloud
  • TRACKER_ORG_ID - Tu ID de organización de Yandex 360

Establece una de las dos. Establecer ambas hace que cada llamada a Tracker falle con Only one of org_id or cloud_org_id should be provided. Los ejemplos a continuación usan TRACKER_CLOUD_ORG_ID; en Yandex 360, reemplaza esa clave con 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:

• Reemplaza los valores de marcador de posición con tus credenciales reales
• Reinicia tu cliente de IA después de los cambios de configuración
• Asegúrate de que uvx esté instalado y disponible en tu PATH del sistema
• Para uso en producción, considera usar variables de entorno en lugar de codificar tokens

Herramientas MCP disponibles

El servidor expone las siguientes herramientas a través del protocolo MCP:

Transporte http

El servidor MCP también se puede ejecutar en modo http transmisible para integraciones basadas en web o cuando el transporte stdio no es adecuado.

Variables de Entorno del 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 el 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

Puedes omitir la configuración de TRACKER_CLOUD_ORG_ID o TRACKER_ORG_ID si usas el siguiente formato al conectarte al Servidor MCP (ejemplo para Claude Code):

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

o

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

También puedes omitir la configuración de la variable de entorno global TRACKER_TOKEN si eliges usar autenticación OAuth 2.0 (ver más abajo).

Autenticación OAuth 2.0

El Servidor MCP de Yandex Tracker admite autenticación OAuth 2.0 como una alternativa segura a los tokens API estáticos. Cuando está configurado, el servidor actúa como un proveedor OAuth, facilitando la autenticación entre tu cliente MCP y los servicios OAuth de Yandex.

Cómo Funciona OAuth

El servidor MCP implementa un flujo estándar de código de autorización OAuth 2.0:

1. Registro del Cliente: Tu cliente MCP se registra con el servidor para obtener credenciales de cliente
2. Autorización: Los usuarios son redirigidos a Yandex OAuth para autenticarse
3. Intercambio de Tokens: El servidor intercambia códigos de autorización por tokens de acceso
4. Acceso a la API: Los clientes usan tokens de portador para todas las solicitudes de API
5. Renovación de Tokens: Los tokens caducados se pueden renovar sin reautenticación

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

Configuración de OAuth

Para habilitar la autenticación OAuth, establece las siguientes variables de entorno:

# 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

Ámbitos de OAuth

Con OAUTH_USE_SCOPES=true (el predeterminado) el servidor solicita, anuncia y requiere los ámbitos de Yandex Tracker tracker:read y tracker:write — o tracker:read solo cuando TRACKER_READ_ONLY=true, por lo que una instancia de solo lectura nunca pide al usuario acceso de escritura. Establecer OAUTH_USE_SCOPES=false elimina los ámbitos del flujo por completo, que es lo que la federación de Yandex Cloud requiere.

Configuración de la Aplicación OAuth de Yandex

1. Ve a Yandex OAuth y crea una nueva aplicación
2. Establece la URL de devolución de llamada a: {MCP_SERVER_PUBLIC_URL}/oauth/yandex/callback
3. Solicita los siguientes permisos:
   • tracker:read - Permisos de lectura para Tracker
   • tracker:write - Permisos de escritura para Tracker
4. Guarda tu ID de Cliente y Secreto de Cliente

OAuth vs Autenticación con Token Estático

Limitaciones del Modo OAuth

• Actualmente, el modo OAuth requiere que el servidor MCP sea accesible públicamente para las URL de devolución de llamada
• El modo OAuth es más adecuado para clientes interactivos que admiten flujos de autenticación basados en web

Uso de OAuth con Clientes MCP

Cuando OAuth está habilitado, los clientes MCP necesitarán:

1. Admitir el flujo de código de autorización OAuth 2.0
2. Manejar la renovación de tokens cuando caduquen los tokens de acceso
3. Almacenar los tokens de renovación de forma segura para la autenticación persistente

Nota: No todos los clientes MCP admiten actualmente la autenticación OAuth. Consulta la documentación de tu cliente para conocer la compatibilidad con OAuth.

Ejemplo de configuración para Claude Code:

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

Almacenamiento de Datos OAuth

El servidor MCP admite dos backends de almacenamiento diferentes para datos OAuth (registros de clientes, tokens de acceso, tokens de renovación y estados de autorización):

Almacén en Memoria (Predeterminado)

El almacén en memoria mantiene todos los datos OAuth en la memoria del servidor. Esta es la opción predeterminada y no requiere configuración adicional.

Características:

• Persistencia: Los datos se pierden cuando el servidor se reinicia
• Rendimiento: Acceso muy rápido ya que los datos se almacenan en memoria
• Escalabilidad: Limitado a una sola instancia del servidor
• Configuración: No requiere dependencias adicionales
• Mejor para: Desarrollo, pruebas o implementaciones de una sola instancia donde perder sesiones OAuth al reiniciar es aceptable

Configuración:

OAUTH_STORE=memory  # Default value, can be omitted

Almacén Redis

El almacén Redis proporciona almacenamiento persistente para datos OAuth usando una base de datos Redis. Esto asegura que las sesiones OAuth sobrevivan a los reinicios del servidor y permite implementaciones de múltiples instancias.

Características:

• Persistencia: Los datos persisten entre reinicios del servidor
• Rendimiento: Acceso rápido con sobrecarga de red
• Escalabilidad: Admite múltiples instancias del servidor que comparten la misma base de datos Redis
• Configuración: Requiere instalación y configuración del servidor Redis
• Mejor para: Implementaciones de producción, configuraciones de alta disponibilidad o cuando las sesiones OAuth deben persistir

Configuración:

# 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

Comportamiento de Almacenamiento:

• Información del Cliente: Almacenada de forma persistente
• Estados OAuth: Almacenados con TTL (tiempo de vida) por seguridad
• Códigos de Autorización: Almacenados con TTL y limpiados automáticamente después de su uso
• Tokens de Acceso: Almacenados con caducidad automática basada en la vida útil del token
• Tokens de Renovación: Almacenados de forma persistente hasta que se revoquen
• Espaciado de Claves: Usa prefijos oauth:* para evitar conflictos con otros datos de Redis

Cifrado de Tokens (Requerido para el Almacén Redis)

Al usar el almacén Redis, debes configurar el cifrado para proteger los tokens OAuth en reposo. Los valores de los tokens se cifran usando Fernet (AES-128) y las claves de Redis usan hashes SHA-256 en lugar de tokens sin procesar, evitando la exposición de tokens si Redis se ve comprometido.

Genera una clave de cifrado:

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

Configuración:

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

La rotación de claves permite actualizaciones de claves sin problemas: agrega la nueva clave primero, espera a que caduquen los tokens antiguos y luego elimina la clave antigua.

Notas Importantes:

• Ambos almacenes usan la misma configuración de conexión Redis que el sistema de caché de herramientas
• Al usar el almacén Redis, asegúrate de que tu instancia de Redis esté correctamente asegurada y accesible
• La configuración OAUTH_STORE solo afecta el almacenamiento de datos OAuth; el caché de herramientas usa TOOLS_CACHE_ENABLED
• El almacén Redis usa serialización JSON para una mejor compatibilidad entre lenguajes y depuración

Autenticación

El Servidor MCP de Yandex Tracker admite múltiples métodos de autenticación con un orden de prioridad claro. El servidor usará el primer método de autenticación disponible según esta jerarquía:

Orden de Prioridad de Autenticación

1. Token OAuth Dinámico (mayor prioridad)

   • Cuando OAuth está habilitado y un usuario se autentica mediante el flujo OAuth
   • Los tokens se obtienen y renuevan dinámicamente por sesión de usuario
   • Admite tanto OAuth estándar de Yandex como OAuth federativo de Yandex Cloud
   • Variables de entorno requeridas: OAUTH_ENABLED=true, OAUTH_CLIENT_ID, OAUTH_CLIENT_SECRET, MCP_SERVER_PUBLIC_URL
   • Variables adicionales 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 Paso Directo

   • Cuando el middleware OAuth de MCP no proporciona un token, el servidor puede leer un token OAuth de Yandex del encabezado Authorization: Bearer <token> entrante
   • Útil detrás de un proxy inverso o puerta de enlace de confianza que autentica usuarios, resuelve su token OAuth de Yandex almacenado y lo inyecta por solicitud
   • El token de MCP OAuth aún tiene prioridad cuando el modo OAuth está habilitado y activo

3. Token OAuth Estático

   • Token OAuth tradicional proporcionado mediante variable de entorno
   • Un solo token usado para todas las solicitudes
   • Variable de entorno requerida: TRACKER_TOKEN (tu token OAuth)

4. Token IAM Estático

   • Token IAM (Identity and Access Management) para autenticación de servicio a servicio
   • Adecuado para sistemas automatizados y pipelines de CI/CD
   • Variable de entorno requerida: TRACKER_IAM_TOKEN (tu token IAM)

5. Token IAM Dinámico (menor prioridad)

   • Obtenido automáticamente usando credenciales de cuenta de servicio
   • El token se obtiene y renueva automáticamente
   • Variables de entorno requeridas: TRACKER_SA_KEY_ID, TRACKER_SA_SERVICE_ACCOUNT_ID, TRACKER_SA_PRIVATE_KEY

Escenarios de Autenticación

Escenario 1: OAuth con Tokens Dinámicos (Recomendado para Uso Interactivo)

# 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

Escenario 2: Token OAuth Estático (Configuración Simple)

# OAuth token
TRACKER_TOKEN=your_oauth_token

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

Escenario 3: Token de Portador de Paso Directo Detrás de un Proxy Inverso

Usa este modo cuando una puerta de enlace de confianza maneja la autenticación del usuario, busca el token OAuth de Yandex del usuario y reenvía la solicitud al servidor MCP con ese token en el encabezado de la solicitud:

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 paso directo se usa solo cuando el middleware OAuth de MCP no ha proporcionado un token de acceso para la solicitud. En implementaciones con OAuth habilitado y una sesión OAuth de MCP activa, el token de MCP OAuth tiene prioridad.

Escenario 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

Escenario 5: Token IAM Dinámico con Cuenta de Servicio

# 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

Escenario 6: OAuth Federativo para Aplicaciones OIDC (Avanzado)

# 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 configuración habilita la autenticación a través de aplicaciones OIDC de Yandex Cloud, que es requerida para cuentas federadas en Yandex Cloud. Los usuarios federados se autentican a través del proveedor de identidad (IdP) de su organización y usan este flujo OAuth para acceder a las APIs de Yandex Tracker.

Notas Importantes

• El servidor verifica los métodos de autenticación en el orden indicado arriba
• Solo se utilizará un método de autenticación a la vez
• Para uso en producción, se recomiendan tokens dinámicos (OAuth o IAM) para mayor seguridad
• Los tokens IAM tienen una vida útil más corta que los tokens OAuth y pueden requerir renovaciones más frecuentes
• Al usar cuentas de servicio, asegúrese de que la cuenta tenga los permisos adecuados para Yandex Tracker

Configuración

Variables de Entorno

# 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

Control de Acceso a Colas

El acceso a las colas se puede delimitar en tres niveles, de grueso a fino:

• TRACKER_LIMIT_QUEUES — lista de permitidos de claves de cola. Las colas fuera de la lista se tratan como no encontradas / no permitidas tanto para lecturas como para escrituras. Las claves se comparan ignorando mayúsculas y minúsculas, aquí y en TRACKER_READ_ONLY_QUEUES, por lo que dev y DEV nombran la misma cola. La única excepción son las herramientas de tablero: un tablero pertenece a la organización en lugar de a una cola, por lo que no se filtran y pueden nombrar una cola restringida en la configuración de un tablero.
• TRACKER_READ_ONLY — cuando true, todas las herramientas de escritura se dan de baja, por lo que toda la instancia es de solo lectura.
• TRACKER_READ_ONLY_QUEUES — lista de permitidos de solo lectura por cola. Las herramientas de escritura permanecen registradas, pero cualquier llamada de mutación (crear/actualizar/mover/comentar/registro de trabajo/enlace, creación de versión de cola) dirigida a una cola listada se rechaza, mientras que las lecturas siguen funcionando. Las colas no listadas aquí permanecen de lectura y escritura.

Las herramientas de proyecto/portafolio/objetivo están fuera de este modelo. Un proyecto, portafolio u objetivo no se puede mapear de manera confiable a una sola cola, por lo que ninguna de las tres configuraciones anteriores las restringe — ni las herramientas de lectura (project_get, project_find, *_get_comments, …) ni las herramientas de escritura (incluidas las de comentarios y listas de verificación). Habilitarlas otorga acceso a nivel de organización a esas entidades para cualquier persona que pueda alcanzar el servidor. Por esta razón son opt-in: se registran solo cuando TRACKER_ENTITIES_ENABLED=true (por defecto false), lo que también mantiene el manifiesto de herramientas pequeño para implementaciones que no las necesitan. TRACKER_READ_ONLY aún se aplica: da de baja las herramientas de escritura de entidades junto con todas las demás herramientas de escritura.

Esto permite que una sola instancia sea de lectura y escritura en algunas colas y de solo lectura en otras al mismo tiempo — por ejemplo, TRACKER_LIMIT_QUEUES=DEV,MGMT junto con TRACKER_READ_ONLY_QUEUES=MGMT da acceso completo a DEV y visibilidad de solo lectura a MGMT. Esto es especialmente útil para una puerta de enlace MCP compartida donde los usuarios finales llegan a Tracker solo a través del servidor y nunca tienen el token sin procesar ellos mismos.

Estas verificaciones son salvaguardas dentro del proceso. Para clientes que tienen el token de Tracker sin procesar directamente, los límites reales también deben aplicarse en el propio token.

Implementación con Docker

Uso de la Imagen Precompilada (Recomendado)

La imagen usa por defecto TRANSPORT=stdio, que se comunica a través de la entrada/salida estándar del contenedor y no abre ningún puerto. Establezca TRANSPORT=streamable-http para los ejemplos a continuación, donde el servidor se alcanza a través de HTTP; para un cliente stdio, ejecute el contenedor con -i y sin -p en su lugar (consulte los ejemplos de Configuración del 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

Construcción de la Imagen Localmente

docker build -t yandex-tracker-mcp .

Docker Compose

Uso de la imagen precompilada:

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

Construcción local:

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

Configuración de Desarrollo

# 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

Licencia

Este proyecto está licenciado bajo los términos especificados en el archivo LICENSE.

Soporte

Para problemas y preguntas:

• Revise la documentación de la API de Yandex Tracker
• Envíe problemas en https://github.com/aikts/yandex-tracker-mcp/issues