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 2: Homebrew macOS
• 🐧 Option 3: Package Installation (Linux)
• 💻 Option 4: Native Installation
• 🔧 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

Pull the official image:

docker pull grafana/mcp-k6:latest

[!NOTE]

That's it! You're ready to run the containerized server.

Proceed to Editor Integrations to configure your editor.

---

Option 2: Homebrew macOS

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

Installation:

# 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 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:

# 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:

# 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:

# 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:

# 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:

mcp-k6 --version

[!NOTE] The binary is installed to /usr/bin/mcp-k6. Proceed to 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:

go version
k6 version
make --version

Installation:

1. Clone the repository:

   git clone https://github.com/grafana/mcp-k6
   cd mcp-k6
   

2. Install the server (embeds resources, installs mcp-k6 into your Go bin):

   make install
   

3. Run the server locally (optional):

   make run
   

4. Verify the binary (optional):

   mcp-k6 --version
   

[!NOTE] Proceed to Editor Integrations to configure your editor.

---

Option 5: k6 Subcommand (xk6)

Use 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:

xk6 build --with github.com/grafana/mcp-k6=.

Run:

./k6 x mcp --transport stdio

Supports the same flags as mcp-k6 (see Configuration Flags).

[!NOTE] Proceed to 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:

mcp-k6 -transport=http -addr=:8080

Docker:

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:

{
  "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:

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

Native:

{
  "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:

claude mcp add --scope=user --transport=stdio k6 -- docker run --rm -i grafana/mcp-k6

Native:

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:

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

Native:

{
  "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:

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

Native:

{
  "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

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

# Then provide your k6 script content

Performance Testing

# 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

# 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

# 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.