Documentationbreadcrumb arrow Grafana k6breadcrumb arrow Set upbreadcrumb arrow Configure your AI assistant
Open source

Configure your AI assistant

mcp-k6 is an experimental Model Context Protocol (MCP) server for k6. Once connected to your AI assistant or MCP-compatible editor, it helps you write better k6 scripts faster and run them with confidence.

What your assistant can do for you

With mcp-k6, your AI assistant can:

  • Write accurate scripts: Create up-to-date scripts by referring to embedded k6 documentation and TypeScript definitions to reduce API hallucinations.
  • Validate scripts: Catch syntax errors, missing imports, and export default function declarations before execution.
  • Run tests locally: Execute scripts and review results without leaving your editor.
  • Generate scripts: Create tests from requirements using guided prompts that follow k6 best practices.
  • Convert browser tests: Transform Playwright tests into k6 browser scripts while preserving test logic.
  • Automate provisioning: Discover Terraform resources in your project to automate Grafana Cloud k6 setup.

Install mcp-k6

Choose one of the following installation methods.

Pull the image:

sh 
docker pull grafana/mcp-k6:latest
docker run --rm grafana/mcp-k6 --version

Homebrew (macOS)

Note

If you run mcp-k6 natively, you must also have k6 installed and available in your PATH.

sh 
brew tap grafana/grafana
brew install mcp-k6
mcp-k6 --version

Linux packages (deb/rpm)

Install mcp-k6 from the .deb or .rpm packages published on the mcp-k6 GitHub releases.

  1. Open the releases page and select a version.
  2. Download the package that matches your Linux distribution and CPU architecture.

You can check your CPU architecture with:

sh 
uname -m

Use the following mapping to pick the right asset:

uname -mDebian/Ubuntu assetFedora/RHEL asset
x86_64amd64 (.deb)x86_64 (.rpm)
aarch64arm64 (.deb)aarch64 (.rpm)

Debian/Ubuntu (.deb)

If you have the GitHub CLI (gh) installed, you can download a specific release asset from the terminal:

sh 
MCP_K6_VERSION="vX.Y.Z"

# For amd64/x86_64:
gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*amd64*.deb"

# For arm64/aarch64:
# gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*arm64*.deb"

sudo apt install ./mcp-k6_*.deb
mcp-k6 --version

If you downloaded the .deb in your browser, run apt from the directory where you saved it:

sh 
sudo apt install ./mcp-k6_*.deb
mcp-k6 --version

Fedora/RHEL (.rpm)

sh 
MCP_K6_VERSION="vX.Y.Z"

# For x86_64:
gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*x86_64*.rpm"

# For aarch64:
# gh release download "$MCP_K6_VERSION" --repo grafana/mcp-k6 --pattern "*linux*aarch64*.rpm"

sudo dnf install ./mcp-k6-*.rpm
mcp-k6 --version

If your distro uses yum instead of dnf, run:

sh 
sudo yum install ./mcp-k6-*.rpm

Build from source

Clone and install with make:

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

Troubleshooting

If your AI assistant cannot connect to the server:

  • Check the logs: Most editors (like Cursor or VS Code) have an “MCP Output” or “Logs” tab. Check there for “command not found” errors.
  • Verify PATH: If running natively, run which k6 in your terminal to ensure k6 is globally accessible.
  • Docker Permissions: Ensure the Docker daemon is running and that your user has permission to execute docker run.
  • Use MCP Inspector: Use the MCP Inspector to debug the connection independently of your editor.

Configure your editor

After you install mcp-k6, refer to Configure MCP clients to register the server with your editor and establish a connection.

Next steps