k6-mcp

oleiade/k6-mcp

3.3

If you are the rightful owner of k6-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

An experimental MCP server for k6, built in Go, providing k6 script validation capabilities through the MCP protocol.

Tools
1
Resources
0
Prompts
0

k6 MCP Server

An experimental MCP (Model Context Protocol) server for k6, written in Go. It offers script validation, test execution, fast full‑text documentation search (embedded SQLite FTS5), and guided script generation.

Features

Prompts

  • Script Generation with /generate_k6_script: Generate production‑ready k6 test scripts from plain‑English requirements. It automatically follows modern testing practices by leveraging embedded best practices, documentation, and type definitions.

Tools

  • Script Validation: validate_k6_script runs k6 scripts with minimal configuration (1 VU, 1 iteration) and returns actionable errors to help quickly produce correct code.
  • Test Execution: run_k6_script runs k6 performance tests locally with configurable VUs, duration, stages, and options, and, when possible, extracts insights from the results.
  • Documentation Search (default): search_k6_documentation provides fast full‑text search over the official k6 docs (embedded SQLite FTS5 index) to help write modern, efficient k6 scripts.
  • Terraform (Grafana k6 Cloud): generate_k6_cloud_terraform_load_test_resource generates a Terraform resource for Grafana Cloud k6, letting you define and provision k6 Cloud tests with the Grafana k6 Terraform provider.

Resources

  • Best Practices Resources: Comprehensive k6 scripting guidelines and patterns to help you write effective, idiomatic, and correct tests.
  • Type Definitions: Up‑to‑date k6 TypeScript type definitions to improve accuracy and editor tooling.

Quick Start

Prerequisites

Install the following:

  • Go 1.24.4+: For building and running the MCP server
  • k6: Must be installed and available in PATH for script execution
  • Just: Command runner for development tasks (recommended)

Install just:

# Just gives access to management commands for the project 
brew install just

Quick Setup

  1. Clone the repository:

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

  2. Install the k6 MCP server (generates the documentation index database, and installs k6-mcp):

    just install

Alternatively, to run without installing system‑wide:

just run

Editor Integration

Cursor IDE

To use this MCP server with Cursor IDE:

  1. Ensure the MCP server is installed (from step 3 above)

  2. Configure MCP settings: Create or update your MCP configuration file (~/.cursor/mcp_servers.json or your editor's MCP config):

    {
  "mcpServers": {
    "k6-mcp": {
      "command": "k6-mcp",
      "env": {}
    }
  }
}

  3. Restart Cursor or reload the MCP configuration.

  4. Use the k6 tools in your Cursor chat:

    • Ask it to validate k6 scripts
    • Request performance test execution
    • Search k6 documentation
    • Generate k6 scripts from requirements
Claude Code

For Claude Code, use the following command to add the k6 MCP server to your configuration:

claude mcp add --scope=user --transport=stdio k6 k6-mcp

Note that this will add the k6 MCP server to your claude code user configuration. If you with to limit the perimeter of the tool to your project, set the scope option to local instead.

Claude Desktop

For Claude Desktop, add the following to your MCP configuration:

{
  "mcpServers": {
    "k6-mcp": {
      "command": "k6-mcp",
      "env": {}
    }
  }
}

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_test

Run k6 performance tests with configurable parameters.

Parameters:

  • script (string, required)
  • vus (number, optional)
  • duration (string, optional)
  • iterations (number, optional)
  • stages (object, optional)
  • options (object, optional)

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

search_documentation

Full‑text search over the embedded k6 docs index (SQLite FTS5).

Parameters:

  • keywords (string, required): FTS5 query string
  • max_results (number, optional, default 10, max 20)

FTS5 tips:

  • Space‑separated words imply AND: checks thresholds → checks AND thresholds
  • Quotes for exact phrases: "load testing"
  • Operators supported: AND, OR, NEAR, parentheses, prefix http*

Returns an array of results with title, content, path.

Available Resources

Best Practices Guide

Access comprehensive k6 scripting best practices covering:

  • Test structure and organization
  • Performance optimization techniques
  • Error handling and validation patterns
  • Authentication and security practices
  • Browser testing guidelines
  • Modern k6 features and protocols

Resource URI: docs://k6/best_practices

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

Just Commands (Recommended)

# Build and run the MCP server (generates the SQLite index if missing)
just run

# Build binary locally (generates the SQLite index if missing)
just build

# Install into your Go bin (generates the SQLite index if missing)
just install

# Optimized release build (stripped, reproducible paths)
just release

# (Re)generate the embedded SQLite docs index
just index

# Optional (experimental embeddings): start vector DBs / helpers
just chroma
just milvus
just ingest
just verify
just reset

Manual Commands

If you prefer not to use just:

# 1) Generate the SQLite FTS5 docs index (required for build/run because it is embedded)
go run -tags fts5 ./cmd/indexer

# 2) Start the MCP server
go run -tags fts5 ./cmd/k6-mcp

# Build a local binary
go build -tags fts5 -o k6-mcp ./cmd/k6-mcp

# Release‑style build (macOS example)
CGO_ENABLED=1 go build -tags 'fts5 sqlite_fts5' -trimpath -ldflags '-s -w' -o k6-mcp ./cmd/k6-mcp

# Run tests
go test ./...

# Lint
golangci-lint run

Project Structure

├── cmd/
│   ├── k6-mcp/               # MCP server entry point
│   └── indexer/              # Builds the SQLite FTS5 docs index into dist/index.db
├── dist/
│   └── index.db              # Embedded SQLite FTS5 index (generated)
├── internal/
│   ├── runner/               # Test execution engine
│   ├── search/               # Full‑text search and indexer
│   ├── security/             # Security utilities
│   └── validator/            # Script validation
├── resources/                # MCP resources
│   ├── practices/            # Best practices guide
│   └── prompts/              # AI prompt templates
├── python-services/          # Optional utilities (embeddings, verification)
└── k6/scripts/               # Generated k6 scripts

Security

The MCP server implements comprehensive security measures:

  • Input validation: Size limits (1MB maximum) and dangerous pattern detection
  • Secure execution: Blocks Node.js modules, system access, and malicious code patterns
  • File handling: Restricted permissions (0600) and secure temporary file management
  • Resource limits: Command execution timeouts (30s validation, 5m tests), max 50 VUs
  • Environment isolation: Minimal k6 execution environment with proper cleanup
  • Docker hardening: Non-root user, read-only filesystem, no new privileges

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 Search

# In your MCP-enabled editor, ask:
"Search for k6 authentication examples"
"How do I use thresholds in k6?"
"Show me WebSocket testing patterns"

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

Build fails with “dist/index.db: no matching files”

Generate the docs index first:

just index

Search returns no results

  • Ensure the index exists: ls dist/index.db
  • Rebuild the index: just index
  • Try simpler queries, or quote phrases: "load testing"

MCP Server Not Found

If your editor can't find the k6-mcp server:

  1. Ensure it's installed: just install
  2. Check your editor's MCP configuration
  3. Verify the server starts: k6-mcp (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 resources don't exceed limits (50 VUs, 5m duration)

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.