Skip to main content
Glama

Servidor MCP QTM4J

npm npm downloads Node License

Un servidor MCP con 42 herramientas para QMetry Test Management for Jira (QTM4J). Busca y gestiona casos de prueba, ciclos, ejecuciones, planes, carpetas, reglas de automatización y metadatos de proyectos desde Claude Desktop, Claude Code, VS Code Copilot, Cursor o cualquier cliente compatible con MCP.

Distribución:

Inicio rápido (no requiere clonar)

Necesitas una clave de API de QMetry (QMetry → API Keys) y Node.js 18+.

Claude Desktop

Edita tu archivo de configuración y reinicia Claude:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Claude Code (CLI)

claude mcp add qtm4j -e QTM4J_API_KEY=your-api-key-here -e QTM4J_REGION=US -- npx -y qtm4j-mcp-server@^0.1

VS Code (modo Agente de GitHub Copilot)

Crea .vscode/mcp.json en tu espacio de trabajo:

{
  "servers": {
    "qtm4j": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": {
        "QTM4J_API_KEY": "${env:QTM4J_API_KEY}",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Cambia el chat de Copilot al modo Agente y las herramientas qtm4j_* aparecerán automáticamente.

Cursor

Añádelo a ~/.cursor/mcp.json (o <project>/.cursor/mcp.json para el nivel de proyecto):

{
  "mcpServers": {
    "qtm4j": {
      "command": "npx",
      "args": ["-y", "qtm4j-mcp-server@^0.1"],
      "env": { "QTM4J_API_KEY": "your-api-key-here" }
    }
  }
}

Las configuraciones de ejemplo anteriores fijan el paquete a ^0.1 para que una futura versión con cambios incompatibles no te actualice automáticamente. Elimina el sufijo @^0.1 si prefieres ejecutar siempre la última versión.

Instalación global (inicio más rápido)

npx vuelve a resolver el paquete en cada lanzamiento, lo que añade unos segundos de latencia al inicio. Si utilizas el servidor con frecuencia, instálalo globalmente y apunta tu cliente directamente al binario:

npm install -g qtm4j-mcp-server

Luego, en la configuración de tu cliente, reemplaza el comando npx:

{
  "mcpServers": {
    "qtm4j": {
      "command": "qtm4j-mcp-server",
      "env": {
        "QTM4J_API_KEY": "your-api-key-here",
        "QTM4J_REGION": "US"
      }
    }
  }
}

Compromiso: inicio instantáneo y funciona sin conexión, pero tendrás que ejecutar npm update -g qtm4j-mcp-server para obtener nuevas versiones.

Related MCP server: qtm4j-mcp-server

Configuración

Variable

Requerido

Predeterminado

Descripción

QTM4J_API_KEY

sí

—

Clave de API de QMetry, enviada en cada solicitud como el encabezado apiKey

QTM4J_REGION

no

US

US → https://qtmcloud.qmetry.com, AU → https://syd-qtmcloud.qmetry.com

💡 Establece QTM4J_REGION=AU si tu instancia de QMetry está en el clúster de Sídney.

Herramientas

Todas las herramientas tienen el prefijo qtm4j_ para evitar colisiones con otros servidores MCP.

Área

Herramientas

Casos de prueba

qtm4j_create_test_case, qtm4j_get_test_case, qtm4j_search_test_cases, qtm4j_update_test_case, qtm4j_delete_test_case, qtm4j_clone_test_cases, qtm4j_create_test_steps, qtm4j_update_test_steps

Ciclos de prueba

qtm4j_create_test_cycle, qtm4j_get_test_cycle, qtm4j_search_test_cycles, qtm4j_update_test_cycle, qtm4j_delete_test_cycle

Ejecuciones de prueba

qtm4j_get_test_cycle_executions, qtm4j_update_test_execution, qtm4j_update_test_step_execution, qtm4j_bulk_update_test_executions

Planes de prueba

qtm4j_create_test_plan, qtm4j_get_test_plan, qtm4j_search_test_plans, qtm4j_update_test_plan, qtm4j_delete_test_plan, qtm4j_link_test_cycles_to_plan, qtm4j_get_linked_test_cycles, qtm4j_unlink_test_cycles_from_plan

Carpetas

qtm4j_list_folders, qtm4j_create_folder

Automatización

qtm4j_link_automation_rule, qtm4j_unlink_automation_rule, qtm4j_run_automation_rules

Metadatos (solo lectura)

qtm4j_get_projects, qtm4j_get_priorities, qtm4j_get_priority_icons, qtm4j_get_statuses, qtm4j_get_environments, qtm4j_get_builds, qtm4j_get_labels, qtm4j_get_components, qtm4j_get_execution_results, qtm4j_get_custom_fields, qtm4j_get_parameters, qtm4j_get_user_permissions

Consulta docs/TOOLS.md para la referencia completa y docs/COOKBOOK.md para ejemplos de prompts que los colegas pueden pegar en cualquier cliente MCP.

Cada herramienta incluye anotaciones (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) para que los clientes puedan decidir si solicitar confirmación. Las herramientas de lectura aceptan un parámetro response_format (json por defecto, o markdown para una salida legible por humanos). Las respuestas grandes se truncan automáticamente a 25k caracteres con una sugerencia para acotar la consulta.

Todas las herramientas validan las entradas con Zod, paginan mediante startAt/maxResults y reintentan automáticamente las respuestas limitadas por tasa (HTTP 429) con retroceso exponencial (hasta 3 intentos).

Pruébalo

Una vez conectado, pregúntale a tu asistente algo como:

Busca en el proyecto de QMetry <tu ID de proyecto> los casos de prueba con estado "To Do" y muéstrame los 5 primeros.

El cliente llamará a qtm4j_search_test_cases y mostrará la respuesta.

Obtén todas las ejecuciones en el ciclo de prueba FS-TR-747 y marca como "Pass" las que no se hayan ejecutado.

Ejemplos de llamadas a herramientas

Reemplaza 10011 a continuación con tu ID numérico de proyecto de Jira. Encuéntralo en la URL del proyecto: …?projectId=10011&projectKey=FS.

// Search test cases
{
  "name": "qtm4j_search_test_cases",
  "arguments": {
    "projectId": 10011,
    "status": ["Approved"],
    "maxResults": 20,
    "response_format": "markdown"
  }
}

// Update an execution result
// (executionResultId: 239444=Pass, 239441=Fail, 239443=Not Executed)
{
  "name": "qtm4j_update_test_execution",
  "arguments": {
    "cycleId": "gxMbioKJsyEr3E",
    "testCaseExecutionId": 287595809,
    "executionResultId": 239444,
    "comment": "Verified on staging"
  }
}

Solución de problemas

  • Las herramientas no aparecen en mi cliente. Reinicia el cliente después de editar la configuración. Comprueba claude mcp list (Claude Code) o el panel MCP de VS Code para ver el estado de la conexión. En la primera ejecución, npx -y qtm4j-mcp-server puede tardar unos segundos en descargar el paquete.

  • 401 Unauthorized. Tu QTM4J_API_KEY no es válida o ha caducado. Genera una nueva en QMetry → API Keys.

  • 404 en endpoints de ejecución o búsqueda. Muchos endpoints requieren el id numérico interno, no la clave legible como FS-TR-747. Llama primero a qtm4j_get_test_cycle para traducir la clave al id interno.

  • Respuesta de carpeta vacía o demasiado grande. Pasa folderId a qtm4j_list_folders para limitar el alcance a un subárbol; los árboles de proyecto completos en proyectos grandes pueden exceder el límite de tamaño de respuesta.

  • projectId rechazado. Usa el ID de proyecto de Jira numérico (p. ej. 10011), no la clave del proyecto ("FS"). Puedes encontrarlo en la URL del proyecto de Jira: …?projectId=10011&projectKey=FS.

Notas

  • Los endpoints de búsqueda usan POST /…/search: los filtros van en el cuerpo bajo filter, la paginación/ordenación en la cadena de consulta. Los manejadores de herramientas envuelven esto por ti.

  • Las respuestas 204 No Content se resuelven como { message: "…" }.

  • La especificación Swagger actualmente no documenta un endpoint de importación de resultados de automatización estilo framework (p. ej. ingesta de JUnit/TestNG/Cucumber); las herramientas de automatización cubren los flujos de ejecución de reglas y enlace de reglas expuestos en la especificación.

Desarrollo

Configuración local si deseas modificar el servidor:

git clone https://github.com/salehrifai42/qmetrymcp.git
cd qmetrymcp
npm install
npm run build
QTM4J_API_KEY=your-key npm start

Prueba los cambios con el Inspector MCP:

QTM4J_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

Errores y contribuciones

¿Encontraste un error o quieres sugerir una función? Abre un issue en https://github.com/salehrifai42/qmetrymcp/issues. Las PR son bienvenidas.

Licencia

MIT

Available Tools

30 tools
bulk_update_test_executionsA

Apply the same execution result, environment, or build to multiple test case executions at once. Use testCycleTestCaseMapIds from get_test_cycle_executions (the 'testCycleTestCaseMapId' field). Returns 204 on success.

Inputs: cycleId (required), testCycleTestCaseMapIds (required), executionResultId, environmentId, +1 more.

clone_test_casesA

Bulk clone one or more test cases into a target project and optional folder. Returns a background task object with a taskId and progressUrl to poll for completion.

Inputs: testcaseIds (required), projectId (required), folderId.

create_folderA

Create a new folder under an existing parent folder. Use parentId=0 for root-level. folderName is required. Returns the created folder with its id. Use list_folders first to find valid parentId values.

Inputs: projectId (required), folderName (required), folderType (required), parentId (required), +1 more.

create_test_caseB

Create a new test case in QMetry. Returns the created test case object including its internal id and key (e.g. FS-TC-123). Priority, status, labels, and components use integer IDs — see field_reference.json for valid values.

Inputs: projectId (required), summary (required), precondition, priority, +7 more.

create_test_cycleA

Create a new test cycle in QMetry. Returns the created cycle with its internal id and key (e.g. FS-TR-123). Use list_folders with folderType=TESTCYCLE to find valid folderId values.

Inputs: projectId (required), summary (required), description, priority, +6 more.

create_test_planA

Create a new test plan in QMetry. Returns the created plan with its internal id and key (e.g. FS-TP-44). Use list_folders with folderType=TESTPLAN to find valid folderId values.

Inputs: projectId (required), summary (required), description, priority, +4 more.

create_test_stepsB

Add one or more test steps to a specific version of a test case. Each step has stepDetails (required), expectedResult, and testData. Returns the created step objects with their IDs.

Inputs: id (required), versionNo (required), steps (required).

delete_test_caseA

Permanently delete a specific version of a test case. If it is the only version, the test case is removed entirely. Returns 204 on success.

Inputs: id (required), versionNo (required).

delete_test_cycleA

Permanently delete a test cycle and all its execution records. This is irreversible. Returns 204 on success.

Inputs: id (required).

delete_test_planA

Permanently delete a test plan. This does not delete the linked test cycles. Returns 204 on success.

Inputs: id (required).

get_linked_test_cyclesA

List all test cycles currently linked to a test plan. Returns paginated list with id, key, status, priority per cycle. Use the plan's internal id (not key).

Inputs: id (required), startAt, maxResults, sort, +1 more.

get_test_caseA

Get a test case by its internal ID or key (e.g. FS-TC-31950). Returns an array of versions, each with versionNo, isLatestVersion, aiGenerated flag, and any test steps.

Inputs: id (required).

get_test_cycleA

Get a test cycle by its key (e.g. FS-TR-747) or internal id. Returns id, key, status, priority, projectId, archived flag. The internal 'id' returned here is required by get_test_cycle_executions and update_test_execution.

Inputs: id (required).

get_test_cycle_executionsA

List all test case executions linked to a test cycle. Requires the internal cycle id (from get_test_cycle, not the key). Returns testCycleTestCaseMapId (needed for bulk_update), testCaseExecutionId (needed for update_test_execution), key, status, and priority per test case.

Inputs: id (required), startAt, maxResults, sort, +1 more.

get_test_planA

Get a test plan by its key (e.g. FS-TP-43) or internal id. Returns id, key, projectId, archived flag. Use the internal 'id' when calling link/unlink/get_linked_test_cycles.

Inputs: id (required).

list_foldersA

List folders of a given type in a project as a nested tree with id, name, parentId, and children. Provide folderId to return only that subtree instead of the full project tree (recommended for large projects).

Inputs: projectId (required), folderType (required), folderId.

run_automation_rulesA

Trigger an automation rule to run against a specific test cycle. testCycleId is the internal id string (from get_test_cycle). Returns a background task object with taskId and progressUrl to poll for completion.

Inputs: automationRuleKey (required), projectId (required), testCycleId (required).

search_test_casesA

Search test cases in a project with optional filters. Returns total count and paginated data with id, key, version info, archived flag. Use status/priority name strings (e.g. 'To Do', 'High') not IDs. projectId must be numeric (10011). Set recursive=true with a folderId to count across all subfolders (returns total only, no data).

Inputs: projectId (required), labels, components, recursive, +9 more.

search_test_cyclesA

Search test cycles in a project. Returns total count and paginated list with id, key, status, priority, archived. The 'id' field in results is the internal ID needed for execution tools.

Inputs: projectId (required), folderId, status, priority, +6 more.

search_test_plansB

Search test plans in a project. Returns total count and paginated list with id, key, projectId, archived. The 'id' field is the internal ID needed for linking cycles.

Inputs: projectId (required), folderId, status, priority, +6 more.

update_test_caseB

Update fields on a specific version of a test case. Requires both the test case id and versionNo (usually 1 for latest). Priority and status take integer IDs. Returns 204 on success.

Inputs: id (required), versionNo (required), summary, precondition, +7 more.

update_test_cycleA

Update a test cycle's metadata (summary, description, priority, status, dates, custom fields). Pass the internal id or key. Returns 204 on success.

Inputs: id (required), summary, description, priority, +5 more.

update_test_executionA

Update a single test case execution result inside a test cycle. Use testCaseExecutionId from get_test_cycle_executions. executionResultId: 239443=Not Executed, 239444=Pass, 239441=Fail, 239442=Work In Progress, 239440=Blocked. Returns 204 on success.

Inputs: cycleId (required), testCaseExecutionId (required), executionResultId, environmentId, +3 more.

update_test_planC

Update a test plan's priority or custom fields. Returns 204 on success.

Inputs: id (required), priority, customFields.

update_test_step_executionA

Update a single step-level execution result within a test case execution. testStepExecutionId comes from get_test_cycle_executions step data. Returns 200 with updated step data.

Inputs: cycleId (required), testStepExecutionId (required), executionResultId, actualResult, +1 more.

update_test_stepsA

Update existing test steps on a test case version. Each step must include its step id (from create_test_steps or get_test_case response). Returns the updated step objects.

Inputs: id (required), versionNo (required), steps (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 30 tools

    Disambiguation5/5

    Each tool targets a distinct entity or operation (folders, test cases, cycles, plans, executions, automation rules, linking). Despite high tool count, descriptions make purposes clear with no overlapping functionality.

    Naming Consistency5/5

    All tools use a consistent verb_noun pattern in snake_case (e.g., create_folder, update_test_execution, search_test_plans). Variations between get/list/search are semantically justified by the operation type.

    Tool Count3/5

    30 tools is on the high side, but the domain (test management) requires many entities and operations. While borderline heavy, most tools serve essential functions without redundancy.

    Completeness4/5

    Covers CRUD for core entities (test cases, cycles, plans, folders), steps, executions (single/bulk), linking, and automation. Missing delete for folders and some retrieval details, but core workflows are complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers