TestRail MCP Server

Interactúa con TestRail para gestionar casos de prueba, proyectos, suites y ejecuciones directamente desde tu cliente de chat de IA.

GitHub
44
Prueba este MCPPatrocinado

Documentación

TestRail MCP Server

Este servidor Model Context Protocol (MCP) proporciona herramientas para interactuar con TestRail directamente desde Claude AI y otros clientes compatibles con MCP como Cursor. Permite gestionar casos de prueba, proyectos, suites, ejecuciones y más sin salir de tu conversación con la IA.

Herramientas disponibles

El servidor MCP de TestRail proporciona las siguientes herramientas:

CategoríaHerramientas
ProyectosgetProjects, getProject
SuitesgetSuites, getSuite, addSuite, updateSuite
CasosgetCase, getCases, addCase, updateCase, deleteCase, getCaseTypes, getCaseFields, copyToSection, moveToSection, getCaseHistory, updateCases, addBdd, getBdd
SeccionesgetSection, getSections, addSection, moveSection, updateSection, deleteSection
EjecucionesgetRuns, getRun, addRun, updateRun
PruebasgetTests, getTest
ResultadosgetResults, getResultsForCase, getResultsForRun, addResultForCase, addResultsForCases
PlanesgetPlans
HitosgetMilestones
Pasos compartidosgetSharedSteps

Uso

Puedes conectar este servidor MCP configurándolo como se muestra a continuación. Este método usa npx para descargar y ejecutar automáticamente la última versión del paquete, eliminando la necesidad de instalación local.

// Example configuration using npx
{
  "mcpServers": {
    "testrail": {
      "command": "npx",
      "args": ["@bun913/mcp-testrail@latest"],
      "env": {
        "TESTRAIL_URL": "https://your-instance.testrail.io", // Replace with your TestRail URL
        "TESTRAIL_USERNAME": "your-email@example.com", // Replace with your TestRail username
        "TESTRAIL_API_KEY": "YOUR_API_KEY" // Replace with your TestRail API key
      }
    }
  }
}

Solución de problemas

  • spawn npx ENOENT / spawn node ENOENT (común en macOS): tu host MCP (Cursor, Claude Code, Claude Desktop, …) no puede encontrar npx o node al momento de iniciar el proceso. La interfaz de chat normalmente muestra esto como un error genérico de "el servidor MCP no funciona" sin detalles útiles; el registro por servidor es la fuente de diagnóstico de referencia.

    Por qué ocurre en macOS: las aplicaciones GUI lanzadas desde el Dock, Spotlight o Finder heredan el PATH mínimo de launchd (/usr/bin:/bin:/usr/sbin:/sbin). Si instalaste Node mediante un gestor de versiones (nvm, asdf, mise, fnm, Volta) o Homebrew para Apple Silicon (/opt/homebrew/bin/), npx se encuentra fuera de ese PATH — solo tu archivo de inicio de shell (~/.zshrc / ~/.bashrc) lo añade. Tu terminal funciona porque el shell ejecutó el archivo de inicio; el proceso de la aplicación GUI nunca lo hizo.

    Diagnostica revisando el registro por servidor en busca de spawn npx ENOENT:

    • Cursor: ~/Library/Application Support/Cursor/logs/<session>/window<N>/exthost/anysphere.cursor-mcp/MCP <server>.log
    • Claude Code / Claude Desktop: ~/Library/Logs/Claude/

    Solución reemplazando "npx" en tu configuración MCP con su ruta absoluta. Ejecuta which npx en tu terminal habitual:

    /Users/you/.nvm/versions/node/v24.15.0/bin/npx   # nvm
/opt/homebrew/bin/npx                            # Apple Silicon Homebrew
/usr/local/bin/npx                               # Intel Homebrew / system Node

    Luego actualiza tu configuración MCP:

    {
  "mcpServers": {
    "testrail": {
      "command": "/Users/you/.nvm/versions/node/v24.15.0/bin/npx",
      "args": ["@bun913/mcp-testrail@latest"],
      "env": {
        "TESTRAIL_URL": "https://your-instance.testrail.io",
        "TESTRAIL_USERNAME": "your-email@example.com",
        "TESTRAIL_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

    Reinicia tu cliente MCP después del cambio. La misma solución aplica a todos los servidores MCP lanzados por npx — si mcp-testrail está fallando por esta razón, es probable que tus otros servidores lanzados por npx también estén fallando.

  • Problemas de autenticación: Verifica tus credenciales de la API de TestRail.

  • Tu conversación es demasiado larga: Usa los parámetros limit y offset para casos de prueba y secciones con el fin de paginar los resultados.

  • Errores HTTP 400 al crear/actualizar casos de prueba: Los proyectos de TestRail tienen diferentes plantillas, campos personalizados y campos obligatorios. Este servidor MCP pasa tus parámetros directamente a la API de TestRail — no los valida ni los transforma. Si encuentras errores 400, define las reglas de tu proyecto en CLAUDE.md o AGENTS.md para que el LLM envíe los parámetros correctos. Por ejemplo:

    # TestRail Rules for This Project
- Project ID: 1
- Always use template 2 (Separated Steps) when creating test cases
  - Use `customStepsSeparated` (array of step objects)
  - Do NOT send `customSteps` or `customExpected` with template 2
- Required custom fields: custom_automation_type (default: 0)
- Call `getCaseFields` at the start of a session to check available fields

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Agradecimientos