k6 MCP Server

这是一个用Go编写的k6的实验性MCP（模型上下文协议）服务器。它提供了脚本验证、测试执行、快速全文文档搜索（嵌入式SQLite FTS5）以及引导式脚本生成。

功能

提示

• 脚本生成：通过/generate_k6_script命令从纯英文需求生成生产就绪的k6测试脚本。它通过利用嵌入的最佳实践、文档和类型定义自动遵循现代测试实践。

工具

• 脚本验证：validate_k6_script使用最小配置（1个虚拟用户，1次迭代）运行k6脚本，并返回可操作错误以帮助快速生成正确的代码。
• 测试执行：run_k6_script本地运行k6性能测试，具有可配置的虚拟用户数、持续时间、阶段和选项，并在可能的情况下从结果中提取见解。
• 文档搜索（默认）：search_k6_documentation提供对官方k6文档（嵌入式SQLite FTS5索引）的快速全文搜索，以帮助编写现代高效的k6脚本。
• Terraform（Grafana k6 Cloud）：generate_k6_cloud_terraform_load_test_resource生成一个用于Grafana Cloud k6的Terraform资源，允许您使用Grafana k6 Terraform提供商定义和供应k6 Cloud测试。

资源

• 最佳实践资源：全面的k6脚本指南和模式，帮助您编写有效的、符合习惯用法且正确的测试。
• 类型定义：最新的k6 TypeScript类型定义，以提高准确性和编辑器工具。

快速开始

先决条件

安装以下内容：

• Go 1.24.4+：用于构建和运行MCP服务器
• k6：必须安装并可在PATH中访问以执行脚本
• Just：开发任务的命令运行器（推荐）

安装just：

# Just提供了项目管理命令的访问权限
brew install just

快速设置

1. 克隆仓库：

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

2. 安装k6 MCP服务器（生成文档索引数据库，并安装k6-mcp）：

   just install
   

或者，不进行全局安装运行：

just run

编辑器集成

Cursor IDE

要使用此MCP服务器与Cursor IDE：

1. 确保已安装MCP服务器（来自上述步骤3）

2. 配置MCP设置： 创建或更新您的MCP配置文件（~/.cursor/mcp_servers.json或您编辑器的MCP配置）：

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

3. 重启Cursor或重新加载MCP配置。

4. 在Cursor聊天中使用k6工具：

   • 请求其验证k6脚本
   • 请求性能测试执行
   • 搜索k6文档
   • 根据需求生成k6脚本

Claude Code

对于Claude Code，使用以下命令将k6 MCP服务器添加到您的配置中：

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

请注意，这会将k6 MCP服务器添加到您的Claude Code用户配置中。如果您希望限制该工具的范围仅限于您的项目，请将作用域选项设置为local。

Claude Desktop

对于Claude Desktop，在您的MCP配置中添加以下内容：

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

可用工具

validate_script

通过使用最小配置（1个虚拟用户，1次迭代）运行k6脚本来验证脚本。

参数：

• script（字符串，必需）

返回值：valid，exit_code，stdout，stderr，error，duration

run_test

使用可配置参数运行k6性能测试。

参数：

• script（字符串，必需）
• vus（数字，可选）
• duration（字符串，可选）
• iterations（数字，可选）
• stages（对象，可选）
• options（对象，可选）

返回值：success，exit_code，stdout，stderr，error，duration，metrics，summary

search_documentation

对嵌入的k6文档索引（SQLite FTS5）进行全文搜索。

参数：

• keywords（字符串，必需）：FTS5查询字符串
• max_results（数字，可选，默认10，最大20）

FTS5提示：

• 空格分隔的单词意味着AND：checks thresholds → checks AND thresholds
• 引号内的精确短语："load testing"
• 支持的操作符：AND，OR，NEAR，括号，前缀http*

返回结果数组，包含title，content，path。

可用资源

最佳实践指南

访问全面的k6脚本最佳实践，涵盖：

• 测试结构和组织
• 性能优化技术
• 错误处理和验证模式
• 认证和安全实践
• 浏览器测试指南
• 现代k6功能和协议

资源URI：docs://k6/best_practices

脚本生成模板

基于AI的结构化工作流程k6脚本生成：

• 研究和发现阶段
• 最佳实践整合
• 生产就绪脚本创建
• 自动验证和测试
• 文件系统集成

资源URI：prompts://k6/generate_script

开发

Just命令（推荐）

# 构建并运行MCP服务器（如果缺少则生成SQLite索引）
just run

# 在本地构建二进制文件（如果缺少则生成SQLite索引）
just build

# 安装到您的Go bin（如果缺少则生成SQLite索引）
just install

# 优化的发布构建（剥离，可重复路径）
just release

# （重新）生成嵌入的SQLite文档索引
just index

# 可选（实验性嵌入）：启动向量数据库/辅助程序
just chroma
just milvus
just ingest
just verify
just reset

手动命令

如果您不想使用just：

# 1) 生成SQLite FTS5文档索引（因为它是嵌入式的，所以构建/运行时需要）
go run -tags fts5 ./cmd/indexer

# 2) 启动MCP服务器
go run -tags fts5 ./cmd/k6-mcp

# 构建本地二进制文件
go build -tags fts5 -o k6-mcp ./cmd/k6-mcp

# 发布风格构建（MacOS示例）
CGO_ENABLED=1 go build -tags 'fts5 sqlite_fts5' -trimpath -ldflags '-s -w' -o k6-mcp ./cmd/k6-mcp

# 运行测试
go test ./...

# 代码检查
golangci-lint run

项目结构

├── cmd/
│   ├── k6-mcp/               # MCP服务器入口点
│   └── indexer/              # 将SQLite FTS5文档索引构建到dist/index.db
├── dist/
│   └── index.db              # 嵌入的SQLite FTS5索引（生成）
├── internal/
│   ├── runner/               # 测试执行引擎
│   ├── search/               # 全文搜索和索引器
│   ├── security/             # 安全实用工具
│   └── validator/            # 脚本验证
├── resources/                # MCP资源
│   ├── practices/            # 最佳实践指南
│   └── prompts/              # AI提示模板
├── python-services/          # 可选实用工具（嵌入，验证）
└── k6/scripts/               # 生成的k6脚本

安全

MCP服务器实现了全面的安全措施：

• 输入验证：大小限制（最大1MB）和危险模式检测
• 安全执行：阻止Node.js模块、系统访问和恶意代码模式
• 文件处理：受限权限（0600）和安全临时文件管理
• 资源限制：命令执行超时（30秒验证，5分钟测试），最多50个虚拟用户
• 环境隔离：具有适当清理的最小k6执行环境
• Docker加固：非root用户，只读文件系统，无新特权

使用示例

基本脚本验证

# 在您的MCP支持的编辑器中询问：
"你能验证这个k6脚本吗？"

# 然后提供您的k6脚本内容

性能测试

# 在您的MCP支持的编辑器中询问：
"使用此脚本进行10个虚拟用户的2分钟负载测试"

# 系统将执行测试并提供详细的指标

文档搜索

# 在您的MCP支持的编辑器中询问：
"搜索k6认证示例"
"如何在k6中使用阈值？"
"显示WebSocket测试模式"

脚本生成

# 在您的MCP支持的编辑器中询问：
"生成一个用于测试带有认证的REST API的k6脚本"
"为电子商务结账流程创建一个浏览器测试"
"生成一个WebSocket负载测试脚本"

故障排除

构建失败，显示“dist/index.db: no matching files”

首先生成文档索引：

just index

搜索未返回结果

• 确保索引存在：ls dist/index.db
• 重建索引：just index
• 尝试更简单的查询，或引用短语："load testing"

MCP服务器未找到

如果您的编辑器找不到k6-mcp服务器：

1. 确保已安装：just install
2. 检查编辑器的MCP配置
3. 验证服务器是否启动：k6-mcp（应显示MCP服务器输出）

测试执行失败

如果k6测试无法执行：

1. 验证k6已安装：k6 version
2. 使用验证工具先检查脚本语法
3. 确保资源不超过限制（50个虚拟用户，5分钟持续时间）

贡献

1. 分叉仓库
2. 创建功能分支
3. 运行测试：go test ./...
4. 运行代码检查：golangci-lint run
5. 提交拉取请求

许可

该项目根据MIT许可协议授权 - 查看LICENSE文件了解详情。