k6

This MCP server acts as an adapter to run k6 load tests through the Model Context Protocol. It exposes two primary actions for executing k6 tests: execute_k6_test for a quick run with sensible defaults, and execute_k6_test_with_options for customizing duration and virtual users (VUs). To start a test, configure the MCP client with the server name (k6) and provide a path to your k6 script. The server will invoke k6 with the requested script and options, and stream real-time output back to you as the test progresses. Typical use cases include quick smoke tests, benchmarking with predetermined defaults (30s duration and 10 VUs), and more granular load tests by specifying custom duration (e.g., 60s) and VUs (e.g., 50).

The MCP API surface includes:

• execute_k6_test(script_file, duration="30s", vus=10): Runs a k6 script with default duration and VUs if not overridden.
• execute_k6_test_with_options(script_file, duration, vus): Runs a k6 script with explicit duration and VUs.

Your workflow often looks like: write a test.js for the target endpoint, then trigger the MCP server with a command such as run k6 test for hello.js. The server will select the available tooling under the hood (k6 binary) to orchestrate the test and return results in real time.

Prerequisites

• Python 3.12 or higher
• k6 load testing tool (install per Grafana k6 docs)
• uv package manager (install per the uv project)

Step-by-step installation

1. Clone the repository git clone https://github.com/qainsights/k6-mcp-server.git cd k6-mcp-server

2. Install Python dependencies via uv/uvx-compatible workflow uv pip install -r requirements.txt

3. Configure environment variables (optional) Create a .env file in the project root with: K6_BIN=/path/to/k6 # Optional: defaults to 'k6' in system PATH

4. Run the MCP server (via uv) as described in the README usage example uv run k6_server.py

Notes:

• If you change where k6 is installed, ensure K6_BIN points to the correct executable.
• Ensure your k6 script (e.g., test.js) is accessible to the MCP process.

Tips and common issues:

• Environment variables: K6_BIN can be used to override the k6 binary path if it's not in your PATH.
• Script visibility: Ensure the MCP server has access to the k6 script you pass (correct filesystem path).
• Real-time output: The MCP server streams test progress; monitor logs for duration/VU thresholds and any errors.
• Compatibility: Verify that your k6 version is compatible with the test script syntax used in test.js.
• If using custom directories, keep the --directory argument accurate to point to where the k6-mcp-server lives.