jmeter-mcp-server

Сервер MCP на stdio для создания, сопровождения, запуска и чтения отчётов тест-планов Apache JMeter — без открытия GUI.

Подключите к этому серверу MCP-совместимый клиент (Claude Code, Claude Desktop и т.д.) — и он сможет собирать тест-план элемент за элементом, запускать в фоне настоящий прогон JMeter без GUI и считывать агрегированную статистику по задержкам/ошибкам — всё через типизированные вызовы инструментов, а не через клики по дереву JMeter.

Почему именно MCP-сервер для этого

LLM уже может написать .jmx-файл с нуля — это просто XML. Проблема в том, что формат .jmx от JMeter — это структура hashTree с множеством хрупких деталей, в которых легко незаметно ошибиться: точные пары guiclass/testclass для каждого элемента, имена свойств, которые не всегда совпадают с подписью в GUI (ThreadGroup.num_threads — это stringProp, а не intProp; типы совпадения утверждений — это целочисленная битовая маска), и строгое соответствие родителя и потомка между каждым элементом и его соседним <hashTree>. Ничто из этого не проверяется автоматически — слегка неверная битовая маска всё равно даёт валидный, загружаемый XML, который просто тихо делает не то (утверждение, которое никогда не срабатывает, слушатель без вывода). Заново восстанавливать всё это по памяти при каждом запросе — значит снова рисковать теми же ошибками.

Этот сервер кодирует это знание ровно один раз — в сериализаторе, проверенном на реальной установке JMeter, — и предоставляет его в виде типизированных инструментов. Конкретные преимущества, которые из этого вытекают:

• Корректность за счёт фиксированного проверенного пути кода. Каждый вызов add_http_sampler проходит через один и тот же проверенный сериализатор, а не через LLM, который каждый раз заново генерирует XML по памяти с риском отклонения или незаметно неверного свойства.

• Дёшевые инкрементальные правки. Тест-план хранится в виде небольшого JSON-дерева со стабильными идентификаторами узлов. Добавление ещё одного утверждения — это один вызов инструмента со ссылкой на parentId, а не чтение и переписывание всего .jmx-файла, чтобы понять, куда вставить изменение. В быстром сравнении бок о бок на плане из 6 элементов JSON-дерево составило ~280 токенов против ~1,580 токенов у эквивалентного .jmx-XML (в котором повторяются пары guiclass/testclass и полный блок saveConfig для каждого слушателя) — и этот разрыв только растёт по мере роста плана, потому что правка JSON-дерева стоит один маленький вызов инструмента независимо от того, насколько большим уже стал весь план.

• Агрегированные результаты, а не сырые сэмплы. get_execution_report разбирает вывод JTL и возвращает вычисленную статистику (количество, процент ошибок, среднее/мин/макс/медиана, p90/p95/p99, пропускная способность, KB/s) — а не выгрузку каждой строки сэмплов, чтобы клиент усреднял их вручную.

• Настоящая асинхронная модель выполнения. execute_test_plan запускает JMeter в фоне и немедленно возвращает executionId; get_execution_status / get_execution_report опрашивают его. Длительные нагрузочные тесты ничего не блокируют в ожидании одного запроса/ответа.

Сгенерированный .jmx соответствует тому же формату, который пишет сам JMeter, так что его в любой момент можно открыть в обычном GUI JMeter, если вы хотите посмотреть на него визуально или передать тому, кто предпочитает UI.

Related MCP server: JMeter MCP Server

Как представлен тест-план

Каждый план хранится в виде JSON-дерева ({id, type, props, children[]}), а не в виде XML-текста. Все инструменты авторинга изменяют это дерево, добавляя дочерний узел под указанный parentId, а в реальный .jmx-файл дерево сериализуется только в момент выполнения. Именно это делает инкрементальные правки дешёвыми и хранит все тонкости XML-схемы в одном месте (src/jmx/serializer.ts), а не размазанными по каждому инструменту.

Инструменты

Авторинг (каждый возвращает id нового узла, используемый как parentId для того, что вы добавите под ним следующим):

Просмотр:

Выполнение и отчёты (асинхронно — запуск происходит в фоне):

Пример рабочего процесса

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

Предварительные требования

• Node.js 18+

• JMeter, установленный локально, с переменной окружения JMETER_HOME, указывающей на каталог установки (тот, который содержит bin/jmeter). На macOS через Homebrew brew install jmeter помещает его в /opt/homebrew/opt/jmeter/libexec.

Добавление этого сервера в Claude Code

Через npx (рекомендуется — опубликовано в npm)

Клонирование и сборка не требуются; npx загружает и запускает опубликованную версию на лету:

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

Подставьте путь JMETER_HOME туда, где на вашей машине установлен JMeter. При желании задайте также JMETER_MCP_WORKSPACE (см. ниже), если хотите хранить планы и результаты выполнения не в месте по умолчанию.

Область действия по умолчанию — local (только этот каталог проекта). Чтобы сделать сервер доступным во всех проектах, добавьте -s user:

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

Проверьте, что он зарегистрировался и отвечает:

claude mcp list

Из локального клона (разработка)

Если вы работаете с кодом этого репозитория, а не с опубликованным пакетом, укажите напрямую собранный dist/index.js:

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

Добавьте это в ~/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"
      }
    }
  }
}

Примечание: в отличие от приложения, запущенного из терминала, Claude Desktop не наследует переменные окружения, экспортированные в вашем профиле оболочки (.zshrc и т.д.), — только действительно общесистемные. Всегда задавайте JMETER_HOME явно в блоке env выше, а не полагайтесь на то, что он уже «установлен на вашей машине».

Переменные окружения

Структура рабочей области

<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

Объём версии v1

Пока не поддерживается (кандидаты на будущий релиз): редактирование/удаление существующих элементов, импорт .jmx, созданного извне, генерация HTML-отчёта-дашборда (-e -o), другие типы сэмплеров/утверждений/экстракторов, CSV Data Set Config, распределённое выполнение.

Лицензия

MIT