K6 MCP Server

1# 🚀 ⚡️ k6-mcp-server
2 
3A Model Context Protocol (MCP) server implementation for running k6 load tests.
4 
5## ✨ Features
6 
7- Simple integration with Model Context Protocol framework
8- Support for custom test durations and virtual users (VUs)
9- Easy-to-use API for running k6 load tests
10- Configurable through environment variables
11- Real-time test execution output
12 
13## 🔧 Prerequisites
14 
15Before you begin, ensure you have the following installed:
16 
17- Python 3.12 or higher
18- k6 load testing tool ([Installation guide](https://grafana.com/docs/k6/latest/set-up/install-k6/))
19- uv package manager ([Installation guide](https://github.com/astral-sh/uv))
20 
21## 📦 Installation
22 
231. Clone the repository:
24 
25```bash
26git clone https://github.com/qainsights/k6-mcp-server.git
27```
28 
292. Install the required dependencies:
30 
31```bash
32uv pip install -r requirements.txt
33```
34 
353. Set up environment variables (optional):
36   Create a `.env` file in the project root:
37 
38```bash
39K6_BIN=/path/to/k6  # Optional: defaults to 'k6' in system PATH
40```
41 
42## 🚀 Getting Started
43 
441. Create a k6 test script (e.g., `test.js`):
45 
46```javascript
47import http from "k6/http";
48import { sleep } from "k6";
49 
50export default function () {
51  http.get("http://test.k6.io");
52  sleep(1);
53}
54```
55 
562. Configure the MCP server using the below specs in your favorite MCP client (Claude Desktop, Cursor, Windsurf and more):
57 
58```json
59{
60  "mcpServers": {
61    "k6": {
62      "command": "/path/to/bin/uv",
63      "args": [
64        "--directory",
65        "/path/to/k6-mcp-server",
66        "run",
67        "k6_server.py"
68      ]
69    }
70  }
71}
72 
73```
743. Now ask the LLM to run the test e.g. `run k6 test for hello.js`. The k6 mcp server will leverage either one of the below tools to start the test.
75 
76- `execute_k6_test`: Run a test with default options (30s duration, 10 VUs)
77- `execute_k6_test_with_options`: Run a test with custom duration and VUs
78 
79![k6-MCP](./images/k6-mcp.png)
80 
81 
82## 📝 API Reference
83 
84### Execute K6 Test
85 
86```python
87execute_k6_test(
88    script_file: str,
89    duration: str = "30s",  # Optional
90    vus: int = 10          # Optional
91)
92```
93 
94### Execute K6 Test with Custom Options
95 
96```python
97execute_k6_test_with_options(
98    script_file: str,
99    duration: str,
100    vus: int
101)
102```
103 
104## ✨ Use cases
105 
106- LLM powered results analysis
107- Effective debugging of load tests
108 
109## 🤝 Contributing
110 
111Contributions are welcome! Please feel free to submit a Pull Request.
112 
113## 📄 License
114 
115This project is licensed under the MIT License - see the LICENSE file for details.
116