From artillery-mcp
Use when running, parsing, or comparing Artillery load tests via the @kosiakmd/artillery-mcp MCP server. Covers flow launching, result bucketing, Fargate dispatch, and raw-text dump parsing.
How this skill is triggered — by the user, by Claude, or both
Slash command
/artillery-mcp:artillery-mcpThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guidance for AI agents using the `@kosiakmd/artillery-mcp` MCP server. This file belongs at `.ai/skills/artillery-mcp/SKILL.md` in your project. If you don't have it yet, run `npx @kosiakmd/artillery-mcp init`.
Guidance for AI agents using the @kosiakmd/artillery-mcp MCP server. This file belongs at .ai/skills/artillery-mcp/SKILL.md in your project. If you don't have it yet, run npx @kosiakmd/artillery-mcp init.
| I want to... | Tool |
|---|---|
| Run a known flow with project conventions (tags, output path) | run_project_lt (requires .artillery-mcp.config.json with flows) |
| Run a specific Artillery YAML with full flag control | run_test_from_file |
| Quickly hit a URL without writing a config | quick_test |
| Launch an LT on AWS ECS/Fargate | run_fargate |
| Parse an existing Artillery JSON report | parse_results |
Parse a saved artillery-output.txt (no JSON available) | read_artillery_output |
| Compare two runs for regression | compare_results |
| Generate a config interactively via wizard | wizard_start → wizard_step → wizard_finalize |
.artillery-mcp.config.jsonEnables run_project_lt and counterBreakdown output. Auto-discovered via:
ARTILLERY_MCP_CONFIG env var (absolute path).artillery-mcp.config.jsonMinimum config for the project launcher:
{
"flows": { "smoke": "tests/load/smoke.yml" },
"environments": ["local", "staging", "prod"],
"defaultTags": { "repo": "my-app" },
"tagTemplates": ["type:{flow}", "env:{env}"],
"outputDir": "load-test-results"
}
Optional counter grouping (adds counterBreakdown field on parse_results / read_artillery_output responses):
"counterGroups": {
"prefix": "checkout.",
"buckets": [
{ "key": "steps", "match": "^checkout\\.step\\." },
{ "key": "other", "default": true }
]
}
First-match-wins across buckets. Any bucket may set "default": true for fallback.
{
"tool": "run_project_lt",
"arguments": {
"flow": "combined",
"environment": "staging",
"note": "canary release v42",
"extraTags": "round:22,feature:wallet-cache",
"templateVars": { "round": "22" }
}
}
Returns { exitCode, elapsedMs, logsTail, jsonResultPath, summary, command, tags, configPath }. The command string is the exact artillery run ... that was executed — useful for pasting into issues.
{
"tool": "run_test_from_file",
"arguments": {
"path": "/abs/path/to/my-test.yml",
"outputJson": "/abs/path/to/results.json",
"record": true,
"tags": "repo:my-app,type:soak",
"name": "my-app soak 2026-04-15",
"environment": "staging"
}
}
--record requires ARTILLERY_CLOUD_API_KEY in env — the MCP passes it through to the spawned CLI.
{
"tool": "parse_results",
"arguments": { "jsonPath": "/abs/path/to/results.json" }
}
Returns: summary (http.* stats), allCounters (every counter verbatim), allRates, allSummaries (nested percentile metrics), and — if config has counterGroups — counterBreakdown with one field per bucket.
{
"tool": "read_artillery_output",
"arguments": {
"path": "/abs/path/to/artillery-output.txt",
"block": "summary",
"maxBytes": 65536
}
}
block: "summary" parses the last Summary report section only (default). "full" parses the whole file. maxBytes caps the returned rawText but parsing sees the full file.
{
"tool": "compare_results",
"arguments": {
"baselinePath": "/abs/path/to/baseline.json",
"currentPath": "/abs/path/to/current.json",
"thresholds": {
"maxLatencyIncrease": 0.2,
"maxErrorRateIncrease": 0.01,
"minThroughputRatio": 0.9
}
}
}
parse_results and read_artillery_output. Relative paths throw.--dry-run in Artillery 2.x. validateOnly: true on run_test_from_file does a client-side YAML structural check (top-level config: + scenarios:).artillery run has no --report flag. If you pass reportHtml, the MCP runs artillery report <outputJson> AFTER the run. Requires outputJson also set.ARTILLERY_MCP_CONFIG at any absolute path.save_config / list_configs / get_config / delete_config / run_saved_config write under ${ARTILLERY_WORKDIR}/saved-configs/. If workdir is read-only (Docker :ro mount), these 5 tools return errors; the other 13 still work.AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION or instance profile) AND a pre-configured artilleryio-cluster ECS cluster in the target region.run_project_lt is not registered unless the config has flows with ≥1 entry.artillery CLI directly so you see stderr in your terminal instead of piped through MCP JSON-RPC.artillery from your CI YAML. MCP is for interactive agent-driven work and ad-hoc analysis.https://raw.githubusercontent.com/kosiakMD/artillery-mcp/main/schemas/config.schema.jsonProvides a checklist for code reviews covering functionality, security, performance, maintainability, tests, and quality. Use for pull requests, audits, team standards, and developer training.
npx claudepluginhub kosiakmd/artillery-mcp-plugin --plugin artillery-mcp