Artillery Mcp

@kosiakmd/artillery-mcp

[ci] [npm version] [license MIT]

Richer drop-in MCP server for Artillery 2.x — exposes the full artillery run and artillery run-fargate flag surface, parses raw text output (artillery-output.txt), returns every counter/rate/summary Artillery produces (not just http.*), and optionally adds a config-driven project launcher and counter-grouping for your custom counters.

Why another MCP server?

The upstream @jch1887/artillery-mcp-server was a solid start but missed several flags our team needed day-to-day. This package is a MIT-licensed fork with broader coverage. See Credits.

Quickstart for agents (Claude Code / Cursor)

# In your project rootnpx @kosiakmd/artillery-mcp init

Scaffolds two files (skipped if they already exist, use --force to overwrite):

• .artillery-mcp.config.json — starter template with commented fields
• .ai/skills/artillery-mcp/SKILL.md — agent-oriented guidance (when to call which tool, common patterns, gotchas)

After editing the config with your real flows/paths, register the MCP in your agent and restart the session:

claude mcp add artillery-mcp -s user \  -e ARTILLERY_WORKDIR="$PWD" \  -e ARTILLERY_CLOUD_API_KEY=a9_... \  -- npx -y @kosiakmd/artillery-mcp

Install / Quickstart (zero-config)

Runs out of the box — no config file needed. Works as an MCP server over stdio for Claude Code, Claude Desktop, Cursor, and any MCP-compatible client.

# Using npx (no install)npx -y @kosiakmd/artillery-mcp
# Or install globallynpm install -g @kosiakmd/artillery-mcpartillery-mcp

Claude Code / Cursor — register as an MCP server in your client config:

{  "mcpServers": {    "artillery-mcp": {      "command": "npx",      "args": ["-y", "@kosiakmd/artillery-mcp"],      "env": {        "ARTILLERY_WORKDIR": "/absolute/path/to/your/project",        "ARTILLERY_CLOUD_API_KEY": "a9_..."      }    }  }}

Claude Code CLI:

claude mcp add artillery-mcp -s user \  -e ARTILLERY_WORKDIR=/abs/path/to/project \  -e ARTILLERY_CLOUD_API_KEY=a9_... \  -- npx -y @kosiakmd/artillery-mcp

Prerequisites: Node.js ≥ 20; Artillery CLI on PATH (npm i -g artillery).

Docker

Multi-arch image — linux/amd64 and linux/arm64, Artillery CLI preinstalled. ~500 MB (Chromium/Playwright browsers skipped — see below). Published to both Docker Hub and GitHub Container Registry from the same build; identical digests.

# Docker Hub (discoverable via `docker search artillery-mcp`)docker pull kosiakmd/artillery-mcp:latest
# GitHub Container Registrydocker pull ghcr.io/kosiakmd/artillery-mcp:latest

Run (mount your project as /workspace):

docker run -i --init --rm \  -v "$PWD":/workspace \  -e ARTILLERY_CLOUD_API_KEY="$ARTILLERY_CLOUD_API_KEY" \  kosiakmd/artillery-mcp:latest

--init ensures the Node process gets reaped on stdin close. Mount /workspace read-write if you want save_config tools to persist to /workspace/saved-configs/; read-only is fine otherwise (the save-config family will simply return errors when called).

MCP client config (Claude Desktop / Cursor) — point the MCP at docker instead of npx:

{  "mcpServers": {    "artillery-mcp": {      "command": "docker",      "args": [        "run", "-i", "--init", "--rm",        "-v", "/absolute/path/to/your/project:/workspace",        "-e", "ARTILLERY_CLOUD_API_KEY",        "kosiakmd/artillery-mcp:latest"      ],      "env": { "ARTILLERY_CLOUD_API_KEY": "a9_..." }    }  }}

Playwright engine? If you use engine: playwright in your Artillery scripts, extend the base image with Chromium:

FROM kosiakmd/artillery-mcp:latestENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=0RUN apk add --no-cache chromium nss freetype harfbuzz ttf-freefont \ && npm i -g @playwright/test \ && npx playwright install chromium

Image tags:

• latest — most recent release
• v0.1.1, v0.1, v0 — pinned by semver (patch / minor / major)

Environment variables

18 base tools (no config needed)

Run tests

• run_test_from_file — full-flag artillery run wrapper (see flag surface above).
• run_test_inline — same but takes YAML text, writes to a tmp file.
• quick_test — artillery quick <url> with rate/count/duration/method/headers/body.
• run_fargate — artillery run-fargate with --region, --cluster, --cpu, --memory, --launch-type, --spot, --subnet-ids, --security-group-ids, --task-role-name, --task-ephemeral-storage, --container-dns-servers, --max-duration, --packages, --secret, --no-assign-public-ip + all run-shared flags.
• run_preset_test — smoke / baseline / soak / spike presets against a URL.
• run_saved_config — re-run a saved config by name.

Parse + inspect results

• parse_results — reads an Artillery JSON report; returns summary + allCounters + allRates + allSummaries + scenarios + metadata.
• read_artillery_output — reads a raw Artillery stdout dump (e.g. artillery-output.txt saved from CI), returns rawText (with tail-truncation), summaryBlock, counters, rates, metrics (nested percentiles).
• run_report — converts an existing JSON results file to HTML via artillery report. Use when you have JSON from CI artifacts and want shareable HTML without re-running.
• compare_results — diff two Artillery JSON results for regression detection.

Saved configs

• save_config / list_configs / get_config / delete_config — persistent named Artillery configs.

Interactive builder

• wizard_start / wizard_step / wizard_finalize — interactive test builder.

Meta

• list_capabilities — versions of Artillery/Node/this server, configured paths, limits.

Optional feature #1 — Project launcher (run_project_lt)

Activated when a .artillery-mcp.config.json file is discovered. Gives you one-liner invocations instead of writing full artillery run ... flag lists.

Discovery precedence:

1. ARTILLERY_MCP_CONFIG env var (absolute path)
2. Walk up from ARTILLERY_WORKDIR / cwd looking for .artillery-mcp.config.json
3. No config → this tool is not registered

Config (.artillery-mcp.config.json):

{  "flows": {    "browse": "tests/load/browse.yml",    "buy": "tests/load/buy.yml",    "combined": "tests/load/combined.yml"  },  "environments": ["local", "staging", "prod"],  "defaultTags": { "repo": "my-app", "owner": "Platform" },  "tagTemplates": ["type:{flow}", "env:{env}", "source:mcp"],  "outputDir": "load-test-results"}

Call:

{ "flow": "buy", "environment": "staging", "note": "canary v42" }

Effective command:

artillery run \  --record \  --name "buy-staging-2026-04-15T00-35-00-000Z" \  --tags "repo:my-app,owner:Platform,type:buy,env:staging,source:mcp" \  -e staging \  --note "canary v42" \  -o /abs/project/load-test-results/buy-staging-2026-04-15T00-35-00-000Z.json \  /abs/project/tests/load/buy.yml

Optional fields:

• tagTemplates — {flow}, {env}, plus any caller-supplied templateVars (e.g. {round})
• outputDir — relative to project root; if missing, outputs land at project root
• defaultTags — merged before templates
• environments — if empty, any environment name is accepted

Override on the call side: name, note, extraTags, outputJson, reportHtml, variables, overrides, record: false, validateOnly, extraArgs, templateVars.

Optional feature #2 — Counter-group bucketing (counterBreakdown)

When you emit custom counters via events.emit('counter', 'shop.step.add_item.happy', 1), Artillery aggregates them into aggregate.counters. This server returns ALL of them in allCounters. Add counterGroups to your config to also get a pre-bucketed counterBreakdown in parse_results and read_artillery_output responses — ideal for CI pass/fail views and semantic grouping.

Config:

{  "counterGroups": {    "name": "shopBreakdown",    "prefix": "shop.",    "buckets": [      { "key": "steps",   "match": "^shop\\.step\\." },      { "key": "cart",    "match": "^shop\\.cart\\." },      { "key": "payment", "match": "^shop\\.payment\\." },      { "key": "flow",    "match": "^shop\\.flow\\." },      { "key": "other",   "default": true }    ]  }}

Example response (parse_results):

{  "summary": { "requestsTotal": 1500, "rpsAvg": 25, "latencyMs": { "p95": 850 }, "errors": {} },  "allCounters": { "shop.step.add_item.happy": 90, "http.requests": 1500, /* ... */ },  "allRates": { "http.request_rate": 25 },  "allSummaries": { "http.response_time": { "min": 45, "p99": 1800 } },  "counterBreakdown": {    "steps": { "shop.step.add_item.happy": 90, "shop.step.add_item.fail": 2 },    "cart": { "shop.cart.failure.quantity_update": 1 },    "payment": {},    "flow": { "shop.flow.started": 100 },    "other": {}  }}

Rules:

• prefix (optional) — counters not starting with this string are ignored
• buckets — ordered; first match wins
• One bucket may have default: true — catches everything that didn't match
• Invalid regex → throws at parse time (fix your config)

Without counterGroups, the counterBreakdown field is simply absent from responses.

Full config reference

{  "flows": { "<name>": "<relative yaml path>" },  // enables run_project_lt  "environments": ["<name>", "..."],              // optional whitelist  "defaultTags": { "<k>": "<v>" },  "tagTemplates": ["type:{flow}", "env:{env}"],  "outputDir": "load-test-results",  "counterGroups": {                              // enables counterBreakdown    "name": "<output field name, cosmetic>",    "prefix": "<optional prefix filter>",    "buckets": [      { "key": "<name>", "match": "<regex>" },      { "key": "<name>", "default": true }    ]  }}

Security

• No network I/O — only spawns the local artillery CLI.
• No eval / Function / dynamic imports.
• No install hooks.
• Dependencies pinned via package-lock.json (committed).
• Published with npm --provenance (SLSA attestation).

Roadmap

Shipped

• v0.1.1 — Docker image (multi-arch amd64/arm64; Artillery CLI preinstalled)
• v0.1.2 — artillery-mcp init scaffolder + shipped SKILL.md agent-guidance template
• v0.1.3 — hard-fail on unknown CLI args, fix Dockerfile missing skills/
• v0.1.4 — dual-publish to Docker Hub alongside GHCR (for docker search discoverability)
• v0.1.7 — run_report tool (JSON → HTML via artillery report); listed in MCP Official Registry (io.github.kosiakMD/artillery-mcp)

v0.2 (next)

• Artillery Cloud API integration — list_recent_runs, get_run_details(runUrl), compare_to_baseline(runUrl). Requires reverse-engineering the artilleryio REST API or partnering with Artillery.io.
• Config schema validation on startup — parse .artillery-mcp.config.json through zod with human-readable error messages ("expected 'flows' to be object, got null at line 3"). Fail-fast with pointer to README.
• YAML config support — accept .artillery-mcp.config.yml using a tiny bundled YAML parser (keeping deps light).
• Playwright Docker variant — kosiakmd/artillery-mcp:latest-playwright with Chromium preinstalled for users with engine: playwright scripts. Separate tag to keep base image small.

v0.3+

• Artillery Lambda + Azure ACI tools — run_lambda, run_aci for parity with run_fargate.
• run_project_lt matrix mode — {"matrix": {"flow": ["free","paid"], "env": ["staging","prod"]}} → 4 runs in parallel.
• Per-flow config overrides — different counterGroups / defaultTags / environments per flow instead of global.
• Streaming intermediate metrics via MCP progress events so agents see RPS/errors mid-run instead of only at completion.
• Built-in presets library — smoke / baseline / soak / spike selectable via config (not just inline YAML).
• Published JSON Schema at stable URL for IDE autocompletion of .artillery-mcp.config.json.
• Plugin API for counter-group matchers beyond regex — e.g. JSONPath, Wasm filter, callback to a user-provided JS.
• Structured run_report variant — return extracted summary text alongside the HTML path, so AI agents can skip loading the file.
• Smithery support — add StreamableHTTP transport + hosted deployment once there's enough demand (requires OAuth-style session config for per-user API keys).

Under consideration

• Grafana / Prometheus integration — push metrics to a user-provided Prometheus endpoint instead of (or in addition to) Artillery Cloud.
• Native Artillery Pro support — enterprise features if users request them.
• TUI dashboard for long-running tests when invoked outside MCP (standalone mode).
• Community MCP catalogs — manual registration on mcp-get.com, PulseMCP for extra discoverability.
• Upstream contribution — offer read_artillery_output, run_fargate, and full flag surface patches back to @jch1887/artillery-mcp-server as PRs; if merged, this fork becomes a thin config-plugin layer on top.

Issues / feature requests / PRs welcome: github.com/kosiakMD/artillery-mcp/issues.

Issues and feature requests welcome: github.com/kosiakMD/artillery-mcp/issues.

Credits

Forked from jch1887/artillery-mcp-server (MIT). See NOTICE for the list of additions and modifications.

License

MIT — see LICENSE. Both the upstream and this fork's copyright notices must be preserved in substantial portions of the software.