Xray MCP Server

xray-cloud-mcp

Un servidor MCP para Xray Cloud (gestión de pruebas para Jira). Permite que un cliente MCP (Claude Code, Claude Desktop, etc.) importe resultados de automatización y gestione entidades de prueba de Xray — Tests, Ejecuciones de Test y Conjuntos de Test — directamente.

Herramientas

Herramienta	API	Lectura/Escritura	Propósito
import_execution_junit	REST	escritura	Importar resultados JUnit XML en una Ejecución de Test
import_execution_xray	REST	escritura	Importar resultados de ejecución nativos Xray-JSON
get_tests	GraphQL	lectura	Consultar issues de Test por JQL
create_test	GraphQL	escritura	Crear un Test Manual/Cucumber/Genérico (con pasos)
update_test	GraphQL	escritura	Cambiar el tipo de un Test y/o añadir pasos
get_test_executions	GraphQL	lectura	Consultar Ejecuciones de Test por JQL
create_test_execution	GraphQL	escritura	Crear una Ejecución de Test, opcionalmente inicializada con tests
add_tests_to_execution	GraphQL	escritura	Añadir tests a una ejecución existente
add_tests_to_test_set	GraphQL	escritura	Añadir tests a un Conjunto de Test existente

Las herramientas de escritura modifican el estado compartido de Jira/Xray — revisa el destino antes de ejecutarlas.

Credenciales

Crea una API Key de Xray en Jira → Xray → Global Settings → API Keys (para un usuario de servicio). Esto genera un client_id + client_secret. El servidor los resuelve al iniciar, nunca desde un archivo en disco, en este orden:

1. Variables de entorno directas XRAY_CLIENT_ID + XRAY_CLIENT_SECRET, si ambas están definidas — lo más simple para uso local y CI.
2. Azure Key Vault — se lee del vault en XRAY_KEY_VAULT_URL mediante DefaultAzureCredential (az login localmente, identidad administrada en Azure). Útil cuando no quieres secretos en el entorno.

Configuración

Variable	Requerida	Predeterminado	Propósito
XRAY_CLIENT_ID / XRAY_CLIENT_SECRET	uno de los dos métodos	—	Credenciales directas
XRAY_KEY_VAULT_URL	(si no se usan variables directas)	—	Azure Key Vault del que leer secretos
XRAY_CLIENT_ID_SECRET_NAME	no	xray-client-id	Nombre del secreto en Key Vault para el client id
XRAY_CLIENT_SECRET_SECRET_NAME	no	xray-client-secret	Nombre del secreto en Key Vault para el client secret
XRAY_BASE_URL	no	https://xray.cloud.getxray.app	Endpoint de Xray Cloud

Si solo necesitas autenticación directa por variables de entorno, las dependencias de @azure/* siguen instaladas pero nunca se invocan. Elimínalas y la rama de Key Vault en src/config.ts si quieres una compilación más ligera.

Compilación

npm install
npm run build        # -> dist/
npm run auth-check   # resolves credentials + obtains a token (prints no secret)

Uso con un cliente MCP

Añádelo a la configuración de tu cliente MCP (p. ej. .mcp.json de Claude Code o la configuración de Claude Desktop), apuntando al entrypoint compilado:

{
  "mcpServers": {
    "xray": {
      "command": "node",
      "args": ["/absolute/path/to/xray-cloud-mcp/dist/index.js"],
      "env": {
        "XRAY_CLIENT_ID": "your-client-id",
        "XRAY_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

O, con Azure Key Vault en lugar de secretos en línea:

"env": {
  "XRAY_KEY_VAULT_URL": "https://your-vault.vault.azure.net"
}

Notas

• Descripción al crear: algunos proyectos de Jira hacen obligatorio el campo Description; create_test lo establece por defecto al resumen para que la creación nunca falle por falta de uno.
• Importación de resultados: apunta import_execution_junit al XML JUnit que produce tu ejecutor de pruebas (Playwright, Jest, JUnit, etc.). Usa import_execution_xray para el JSON nativo más completo de Xray.
• Solo stdio: el servidor habla MCP a través de stdio; los diagnósticos van a stderr (stdout es el canal del protocolo).

Licencia

MIT — consulta LICENSE.