jmeter-mcp-server

Un servidor stdio MCP para crear, mantener, ejecutar y leer informes de planes de pruebas de Apache JMeter — sin abrir la GUI.

Puedes apuntar un cliente compatible con MCP (Claude Code, Claude Desktop, etc.) a este servidor y podrá componer un plan de pruebas elemento por elemento, lanzar una ejecución real de JMeter en modo no gráfico en segundo plano, y recuperar estadísticas agregadas de latencia/error, todo mediante llamadas a herramientas tipadas en lugar de hacer clic en la vista de árbol de JMeter.

Por qué un servidor MCP para esto, específicamente

Un LLM ya puede escribir un archivo .jmx desde cero — es solo XML. El problema es que el formato .jmx de JMeter es una estructura hashTree con muchos detalles frágiles y fáciles de estropear de forma sutil: los pares exactos guiclass/testclass por elemento, nombres de propiedad que no siempre coinciden con la etiqueta de la GUI (ThreadGroup.num_threads es un stringProp, no un intProp; los tipos de coincidencia de las aserciones son una máscara de bits entera), y el emparejamiento estricto padre/hijo entre cada elemento y su <hashTree> hermano. Nada de eso se autocomprueba: una máscara de bits ligeramente incorrecta sigue produciendo XML válido y cargable que simplemente hace algo incorrecto en silencio (una aserción que nunca se dispara, un listener sin salida). Reconstruir todo eso de memoria en cada petición implica arriesgarse a repetir los mismos errores cada vez.

Este servidor codifica ese conocimiento una única vez, en un serializador que ha sido probado contra una instalación real de JMeter, y lo expone como herramientas tipadas. Los beneficios concretos que se derivan de ello:

• Corrección mediante una ruta de código fija y probada. Cada llamada a add_http_sampler pasa por el mismo serializador verificado, en lugar de que un LLM regenere el XML de memoria cada vez con posibilidad de desviación o de una propiedad sutilmente incorrecta.

• Ediciones incrementales económicas. Un plan de pruebas se almacena como un pequeño árbol JSON con ids de nodo estables. Añadir una aserción más es una única llamada a una herramienta que referencia un parentId, no leer y reescribir un archivo .jmx completo para averiguar dónde insertar un cambio. En una comparación rápida con un plan de 6 elementos, el árbol JSON resultó tener ~280 tokens frente a ~1.580 tokens para el .jmx XML equivalente (que repite los pares guiclass/testclass y un bloque saveConfig completo por listener) — y esa diferencia no hace más que ampliarse a medida que un plan de pruebas crece, ya que editar el árbol JSON cuesta una pequeña llamada a una herramienta independientemente del tamaño total que ya tenga el plan.

• Resultados agregados, no muestras brutas. get_execution_report analiza la salida JTL y devuelve estadísticas calculadas (recuento, % de error, media/mín/máx/mediana, p90/p95/p99, throughput, KB/s) — no un volcado de cada fila de muestras para que el cliente calcule la media a mano.

• Un modelo de ejecución asíncrona real. execute_test_plan inicia JMeter en segundo plano y devuelve inmediatamente un executionId; get_execution_status / get_execution_report lo consultan periódicamente. Las pruebas de carga de larga duración no bloquean nada esperando una única petición/respuesta.

El .jmx generado sigue el mismo formato que escribe el propio JMeter, por lo que se puede abrir en la GUI real de JMeter en cualquier momento si quieres inspeccionarlo visualmente o entregárselo a alguien que prefiera la interfaz de usuario.

Related MCP server: JMeter MCP Server

Cómo se representa un plan de pruebas

Cada plan se almacena como un árbol JSON ({id, type, props, children[]}) en lugar de como texto XML. Todas las herramientas de creación modifican este árbol añadiendo un hijo bajo un parentId dado, y el árbol solo se serializa en un archivo .jmx real en el momento de la ejecución. Esto es lo que hace que las ediciones incrementales sean económicas y mantiene el conocimiento del engorroso esquema XML en un solo lugar (src/jmx/serializer.ts) en lugar de repartido por todas las herramientas.

Herramientas

Creación (cada una devuelve el id del nuevo nodo, que se usa como parentId para lo que quieras adjuntar debajo a continuación):

Inspección:

Ejecución e informes (asíncrono: la ejecución se produce en segundo plano):

Ejemplo de flujo de trabajo

create_test_plan            → { planId, rootNodeId }
add_thread_group             (parentId: rootNodeId)  → { nodeId: threadGroupId }
add_http_sampler              (parentId: threadGroupId) → { nodeId: samplerId }
add_response_assertion        (parentId: samplerId)
add_aggregate_report_listener (parentId: threadGroupId)
execute_test_plan             (planId) → { executionId }
get_execution_status           (executionId)   ← poll until "completed"
get_execution_report            (executionId) → aggregated latency/error stats

Requisitos previos

• Node.js 18+

• JMeter instalado localmente, con la variable de entorno JMETER_HOME apuntando al directorio de instalación (el que contiene bin/jmeter). En macOS mediante Homebrew, brew install jmeter lo instala en /opt/homebrew/opt/jmeter/libexec.

Añadir este servidor a Claude Code

Mediante npx (recomendado: publicado en npm)

No hace falta clonar ni compilar; npx descarga y ejecuta la versión publicada sobre la marcha:

claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

Ajusta la ruta de JMETER_HOME a dondequiera que esté instalado JMeter en tu máquina. Opcionalmente, configura también JMETER_MCP_WORKSPACE (ver más abajo) si quieres que los planes y las ejecuciones se almacenen en un lugar distinto del predeterminado.

El alcance predeterminado es local (solo este directorio de proyecto). Para que esté disponible en todos los proyectos, añade -s user:

claude mcp add jmeter -s user \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- npx -y jmeter-mcp-server

Confirma que se ha registrado y que responde:

claude mcp list

Desde un clon local (desarrollo)

Si estás trabajando con el código de este repositorio en lugar de usar el paquete publicado, apunta directamente al dist/index.js compilado:

npm install
npm run build
claude mcp add jmeter \
  -e JMETER_HOME=/opt/homebrew/opt/jmeter/libexec \
  -- node /absolute/path/to/jmeter-mcp-server/dist/index.js

Claude Desktop

Añade esto a ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jmeter": {
      "command": "npx",
      "args": ["-y", "jmeter-mcp-server"],
      "env": {
        "JMETER_HOME": "/opt/homebrew/opt/jmeter/libexec"
      }
    }
  }
}

Nota: a diferencia de una aplicación lanzada desde la terminal, Claude Desktop no hereda las variables de entorno exportadas en tu perfil de shell (.zshrc, etc.) — solo las verdaderamente globales del sistema. Configura siempre JMETER_HOME explícitamente en el bloque env anterior, en lugar de confiar en que ya esté «definida en tu máquina».

Variables de entorno

Estructura del espacio de trabajo

<workspace>/
  plans/<planId>/plan.json           # JSON tree — source of truth for a plan
  executions/<executionId>/
    generated.jmx                    # serialized at execute_test_plan time
    aggregate-report.jtl             # output of the Aggregate Report listener, if present
    summary-report.jtl               # output of the Summary Report listener, if present
    jmeter.log
    meta.json                        # execution status, pid, timestamps, exit code

Alcance de la v1

Aún no compatible (candidatos para una versión futura): editar/eliminar elementos existentes, importar un .jmx creado externamente, generar el informe de panel HTML (-e -o), otros tipos de muestreador/aserción/extractor, CSV Data Set Config, ejecución distribuida.

Licencia

MIT