# k6 MCP Server

An **experimental** MCP (Model Context Protocol) server for k6, written in Go. It offers script validation, test execution, documentation browsing, and guided script generation.

> [!IMPORTANT]
> This project is still experimental. Expect sharp edges, keep a local clone up to date, and share feedback or issues so we can iterate quickly.

## Features

### Tools
- **Script Validation**: `validate_script` runs k6 scripts with minimal configuration (1 VU, 1 iteration) and returns actionable errors to help quickly produce correct code.
- **Test Execution**: `run_script` runs k6 performance tests locally with optional VUs, duration, and iteration overrides, and, when possible, extracts insights from the results.
- **Documentation Browsing**: `list_sections` and `get_documentation` provide structured navigation of the official k6 docs and allow retrieving full markdown for specific sections. Docs are downloaded on first use, cached locally, and automatically kept fresh via periodic staleness checks.

### Resources
- **Best Practices Resources**: Comprehensive k6 scripting guidelines and patterns to help you write effective, idiomatic, and correct tests.

### Prompts
- **Script Generation** with `generate_script`: Generate production-ready k6 test scripts from plain-English requirements. It automatically follows modern testing practices by leveraging embedded best practices and the official k6 documentation.

## Getting Started

Choose your preferred installation method:
- [🐳 Option 1: Docker (Recommended)](#option-1-docker-recommended)
- [🍎 Option 2: Homebrew macOS](#option-2-homebrew-macos)
- [🐧 Option 3: Package Installation (Linux)](#option-3-package-installation-linux)
- [💻 Option 4: Native Installation](#option-4-native-installation)
- [🔧 Option 5: k6 Subcommand (xk6)](#option-5-k6-subcommand-xk6)
---
### Option 1: Docker (Recommended)

The easiest way to get started. The Docker image includes k6 and all dependencies.

**Prerequisites:**
- **Docker**: Install from [docker.com](https://www.docker.com/get-started)

**Pull the official image**:
   ```bash
   docker pull grafana/mcp-k6:latest
   ```
> [!NOTE]
> ### That's it! You're ready to run the containerized server.
> Proceed to [Editor Integrations](#editor-integrations) to configure your editor.
---
### Option 2: Homebrew macOS

Install mcp-k6 using Homebrew. k6 will be automatically installed as a dependency.

**Installation:**

```bash
# Add the grafana homebrew tap repository
brew tap grafana/grafana

# Install mcp-k6
brew install mcp-k6

# Verify installation
mcp-k6 --version
```
> [!NOTE]
> To update to a newer version, download and install the latest formula again, or use `brew upgrade` if installed from the tap.
> Proceed to [Editor Integrations](#editor-integrations) to configure your editor.

---
### Option 3: Package Installation (Linux)

Pre-built packages are available for Debian/Ubuntu and RHEL/Fedora/CentOS distributions.

> **Version naming:** Git tags include the `v` prefix (e.g. `v0.2.0`), but release files drop it. Replace `VERSION` below with just the numeric part (`0.2.0`).

**Prerequisites:**
- **k6** (recommended): Should be installed for script execution

#### Debian/Ubuntu (.deb)

Download and install the `.deb` package from the [latest release](https://github.com/grafana/mcp-k6/releases/latest):

```bash
# For amd64 (x86_64)
curl -LO https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_amd64.deb
sudo dpkg -i mcp-k6_0.2.0_linux_amd64.deb

# For arm64
curl -LO https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_arm64.deb
sudo dpkg -i mcp-k6_0.2.0_linux_arm64.deb
```

Or install directly with `apt`:
```bash
# Download the package
curl -LO https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_amd64.deb

# Install with apt (resolves dependencies)
sudo apt install ./mcp-k6_0.2.0_linux_amd64.deb
```

#### RHEL/Fedora/CentOS (.rpm)

Download and install the `.rpm` package from the [latest release](https://github.com/grafana/mcp-k6/releases/latest):

```bash
# For amd64 (x86_64)
curl -LO https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_amd64.rpm
sudo rpm -i mcp-k6_0.2.0_linux_amd64.rpm

# For arm64
curl -LO https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_arm64.rpm
sudo rpm -i mcp-k6_0.2.0_linux_arm64.rpm
```

Or use `dnf`/`yum`:
```bash
# Fedora/RHEL 8+
sudo dnf install https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_amd64.rpm

# CentOS/RHEL 7
sudo yum install https://github.com/grafana/mcp-k6/releases/latest/download/mcp-k6_VERSION_linux_amd64.rpm
```

**Verify installation:**
```bash
mcp-k6 --version
```

> [!NOTE]
> The binary is installed to `/usr/bin/mcp-k6`.
> Proceed to [Editor Integrations](#editor-integrations) to configure your editor.
---

### Option 4: Native Installation

For development or if you prefer running the server natively.

**Prerequisites:**
- **Go 1.24.4+**: For building and running the MCP server
- **k6**: Must be installed and available in PATH for script execution
- **GNU Make**: Provides the automation targets used by this project (typically preinstalled on macOS/Linux)

Verify the tooling:
```bash
go version
k6 version
make --version
```

**Installation:**

1. **Clone the repository**:
   ```bash
   git clone https://github.com/grafana/mcp-k6
   cd mcp-k6
   ```

2. **Install the server** (embeds resources, installs `mcp-k6` into your Go bin):
   ```bash
   make install
   ```

3. **Run the server locally** (optional):
   ```bash
   make run
   ```

4. **Verify the binary** (optional):
   ```bash
   mcp-k6 --version
   ```

> [!NOTE]
> Proceed to [Editor Integrations](#editor-integrations) to configure your editor.
---
### Option 5: k6 Subcommand (xk6)

Use [xk6](https://github.com/grafana/xk6) to build a custom k6 binary that embeds mcp-k6 as a `k6 x mcp` subcommand. This gives you a single binary that runs both k6 load tests and the MCP server.

**Prerequisites:**
- **xk6**: `go install go.k6.io/xk6/cmd/xk6@latest`
- **Go 1.24.4+**

**Build:**
```bash
xk6 build --with github.com/grafana/mcp-k6=.
```

**Run:**
```bash
./k6 x mcp --transport stdio
```

Supports the same flags as `mcp-k6` (see [Configuration Flags](#configuration-flags)).

> [!NOTE]
> Proceed to [Editor Integrations](#editor-integrations) to configure your editor.
---
## HTTP Transport Mode

mcp-k6 supports two transport modes:

1.  **Stdio (Default):** Best for local, single-user setups where your editor or MCP client manages the server process directly.
2.  **Streamable HTTP:** Ideal for remote deployments, shared team instances, or complex network setups where clients connect over the network.

### Running in HTTP Mode

To start the server in HTTP mode, use the `-transport=http` flag:

**Native:**
```bash
mcp-k6 -transport=http -addr=:8080
```

**Docker:**
```bash
docker run -p 8080:8080 grafana/mcp-k6 -transport=http -addr=:8080
```

### Configuration Flags

-   `-addr`: Listening address (default `:8080`). To listen on all interfaces, use `:8080` or `0.0.0.0:8080`.
-   `-endpoint`: Endpoint path for the MCP server (default `/mcp`).
-   `-stateless`: Run in stateless mode without session tracking (default `false`).
-   `-preload`: Download all doc bundles at startup instead of on first request (default `false`).

## Remote Deployment (Team Usage)

You can deploy mcp-k6 as a shared service for your team. This allows multiple users to connect their MCP clients (like Claude Desktop or Cursor) to a central instance, sharing the execution environment.

**Example Deployment:**

1.  Deploy the Docker container to your infrastructure (e.g., Kubernetes, EC2).
2.  Expose port `8080`.
3.  Configure the server to listen on all interfaces: `-addr=0.0.0.0:8080`.

**Security Note:** The server has no built-in authentication. It should be deployed in a trusted network (VPN, private VPC) or behind a secure proxy that handles authentication.

### Editor Integrations

`mcp-k6` speaks MCP over stdio by default, but can be configured for Streamable HTTP.

#### Connect via Streamable HTTP

If you are running the server in HTTP mode (locally or remotely), configure your editor to connect via Streamable HTTP:

```json
{
  "mcpServers": {
    "remote-k6": {
      "url": "http://your-server-ip:8080/mcp"
    }
  }
}
```

#### Cursor IDE

Create or update `~/.cursor/mcp_servers.json` (or the profile-specific config):

**Docker:**
```json
{
  "mcpServers": {
    "k6": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "grafana/mcp-k6"]
    }
  }
}
```

**Native:**
```json
{
  "mcpServers": {
    "mcp-k6": {
      "command": "mcp-k6"
    }
  }
}
```

Restart Cursor or reload the MCP configuration, then call the tools from chat (validate scripts, run load tests, search docs, generate scripts).

#### Claude Code

Add the server to Claude Code:

**Docker:**
```bash
claude mcp add --scope=user --transport=stdio k6 -- docker run --rm -i grafana/mcp-k6
```

**Native:**
```bash
claude mcp add --scope=user --transport=stdio k6 mcp-k6
```

Use `--scope=local` if you prefer the configuration to live inside the current project. Reload the workspace to pick up the new server.

#### Claude Desktop

Place one of the following snippets in your Claude Desktop MCP configuration file (create it if necessary):

**Docker:**
```json
{
  "mcpServers": {
    "k6": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "grafana/mcp-k6"]
    }
  }
}
```

**Native:**
```json
{
  "mcpServers": {
    "mcp-k6": {
      "command": "mcp-k6"
    }
  }
}
```

Restart the desktop app or reload its MCP plugins afterwards.

#### Codex CLI

Codex CLI (experimental) supports MCP servers over stdio.

1. Locate your Codex configuration (see `codex help config` for the exact path on your system).
2. Add or merge one of the following blocks under the top-level `mcpServers` key:

**Docker:**
```json
{
  "mcpServers": {
    "k6": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "grafana/mcp-k6"]
    }
  }
}
```

**Native:**
```json
{
  "mcpServers": {
    "mcp-k6": {
      "command": "mcp-k6"
    }
  }
}
```

3. Restart Codex or reload its configuration (`codex reload`) to make the new server available.


## Available Tools

### validate_script

Validate a k6 script by running it with minimal configuration (1 VU, 1 iteration).

Parameters:
- `script` (string, required)

Returns: `valid`, `exit_code`, `stdout`, `stderr`, `error`, `duration`

### run_script

Run k6 performance tests with configurable parameters.

Parameters:
- `script` (string, required)
- `vus` (number, optional): Virtual users override. When omitted, script-defined options and k6 defaults are used.
- `duration` (string, optional): Duration override, max `5m`. When omitted, script-defined options and k6 defaults are used.
- `iterations` (number, optional): Iterations override. When provided with a positive value, it takes precedence over `duration`.

Returns: `success`, `exit_code`, `stdout`, `stderr`, `error`, `duration`, `metrics`, `summary`

### list_sections

Browse the documentation hierarchy without overwhelming model context. The tool returns a depth-limited tree (default depth 1) so you can progressively expand only the branches you need.

Parameters:
- `version` (string, optional): Specific docs version (`v1.4.x`, `all` for list).
- `category` (string, optional): Filter to a top-level docs category.
- `depth` (number, optional, default 1, max 5): How many levels of children to include in the tree. Depth counts from the root you request.
- `root_slug` (string, optional): List the immediate children under this slug (e.g., `using-k6`), just like `ls` inside a folder. Combine with `depth` to include deeper descendants.

Response highlights:
- `tree`: Depth-limited nodes with inline `children`, `child_count`, and `has_more` so you know when to fetch another layer.
- `version` and `available_versions`: Confirm the docs version in use.
- `depth` and `root_slug`: Echo the arguments used so agents can decide whether to dive deeper.

### get_documentation

Retrieve full markdown content for a specific documentation section.

Parameters:
- `slug` (string, required): Section slug (use list_sections to discover them).
- `version` (string, optional): Specific docs version (`v1.4.x`, etc.).

Returns `section`, `content`, `version`, and `available_versions`.

## Available Resources

### Script Generation Template

AI-powered k6 script generation with structured workflow:
- Research and discovery phase
- Best practices integration
- Production-ready script creation
- Automated validation and testing
- File system integration

**Resource URI:** `prompts://k6/generate_script`

## Development

Run `make list` to get a list of available Make commands.

## Usage Examples

### Basic Script Validation

```bash
# In your MCP-enabled editor, ask:
"Can you validate this k6 script?"

# Then provide your k6 script content
```

### Performance Testing

```bash
# In your MCP-enabled editor, ask:
"Run a load test with 10 VUs for 2 minutes using this script"

# The system will execute the test and provide detailed metrics
```

### Documentation Browsing

```bash
# In your MCP-enabled editor, ask:
"List the top-level k6 documentation sections"
"Show me the scenarios section documentation"
"Fetch the markdown for javascript-api/k6-http/request"
```

### Script Generation

```bash
# In your MCP-enabled editor, ask:
"Generate a k6 script to test a REST API with authentication"
"Create a browser test for an e-commerce checkout flow"
"Generate a WebSocket load test script"
```

## Troubleshooting

### MCP Server Not Found
If your editor can't find the mcp-k6 server:
1. Ensure it's installed: `make install`
2. Check your editor's MCP configuration
3. Verify the server starts: `mcp-k6` (should show MCP server output)

### Test Execution Failures
If k6 tests fail to execute:
1. Verify k6 is installed: `k6 version`
2. Check script syntax with the validate tool first
3. Ensure duration doesn't exceed the 5m limit

## Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests: `go test ./...`
4. Run linter: `golangci-lint run`
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.