# Grafana k6 Cloud MCP

> Grafana k6 Cloud (Load Testing) MCP Server lets you manage your entire performance testing lifecycle through natural conversation. You can list and retrieve details for all your load tests, start new test runs, and analyze detailed performance metrics (latency, error rates, throughput) for completed runs, all without jumping between dashboards. It’s your AI agent's direct line to k6 Cloud infrastructure.

## Overview
- **Category:** ship-it
- **Price:** Free
- **Tags:** load-testing, performance-engineering, stress-testing, test-automation, cloud-infrastructure, metrics

## Description

Man, you wanna take charge of your performance testing without jumping through hoops? This server gives your AI agent a direct line to k6 Cloud infrastructure. You'll manage your whole load testing lifecycle just by talking to your agent. You don't gotta switch between dashboards anymore.

**Managing Your Tests and Projects**

Your agent can list all the organizations you've got, giving you the names, IDs, and how many members are in each. It can also list every project inside a specific organization. When it comes to the tests themselves, your agent can list all the load tests available on Grafana Cloud k6, showing you their names, IDs, and the status of their last run. You can also list all the test runs, seeing the IDs, current status (like QUEUED, RUNNING, or FINISHED), how many Virtual Users (VU) were used, and when they ran.

**Running and Stopping Tests**

If you need a new test, your agent can initiate a test run on k6 Cloud and spit out the new active run ID so you can track it. If a test's running too long or you gotta stop it, your agent can halt a currently running k6 Cloud test execution, saving you some resources.

**Checking the Results**

Once a test is done, your agent can pull the full details for a specific k6 test run. It can also grab detailed performance metrics—that means latency, error rates, and throughput—for a completed k6 run. You can get the full details for a specific k6 test configuration. Need to know if your app hit its targets? Your agent can fetch the evaluation results to verify if a k6 run met its set performance thresholds. You can also check the status of test runs to see if they're QUEUED, RUNNING, or FINISHED.

This setup lets your AI agent handle everything from setting up the test to analyzing the final numbers, all without you ever leaving your chat window. It’s a complete control panel for k6 Cloud, straight into your workflow.

## Tools

### get_run
Retrieves the full details for a specific k6 test run.

### get_run_metrics
Gets detailed performance metrics (latency, error rates, throughput, etc.) for a completed k6 run.

### get_run_thresholds
Fetches the evaluation results to verify if a k6 run met its set performance thresholds.

### get_test
Retrieves the full details for a specific k6 test configuration.

### list_organizations
Lists all organizations on k6 Cloud, providing names, IDs, and member counts.

### list_projects
Lists all projects within a specific k6 Cloud organization.

### list_runs
Lists test runs, showing IDs, status (QUEUED/RUNNING/FINISHED), VU counts, and timestamps.

### list_tests
Lists all load tests available on Grafana Cloud k6, showing names, IDs, and last run statuses.

### start_test_run
Initiates a new k6 Cloud test run and returns the new active run ID for tracking.

### stop_test_run
Stops a currently running k6 Cloud test execution.

## Prompt Examples

**Prompt:** 
```
List all my load tests in k6 Cloud
```

**Response:** 
```
I've found 4 load tests: 'API Stress Test' (ID: 123), 'Checkout Flow' (ID: 456), 'Inventory Spike' (ID: 789), and 'Frontend Smoke' (ID: 012). Which one would you like to check the last run status for?
```

**Prompt:** 
```
Show me the performance metrics for the last run of the 'API Stress Test'
```

**Response:** 
```
Retrieving metrics for run ID 'run-98765'… Average response time: 142ms, P95: 285ms, Failed requests: 0.2%, Max VUs: 500. All metrics are within acceptable ranges. Would you like me to check the threshold details?
```

**Prompt:** 
```
Start a new test run for 'Checkout Flow' (ID: 456)
```

**Response:** 
```
Trigging new run for 'Checkout Flow'… Done. New Run ID is 'run-13579'. It's currently in the QUEUED state. I'll let you know when the first VUs start injecting traffic.
```

## Capabilities

### List and manage test artifacts
The agent retrieves names, IDs, and configurations for all available load tests and projects within your k6 Cloud account.

### Execute and stop test runs
The agent starts a new test run on k6 Cloud infrastructure or immediately halts an active execution, controlling system resources.

### Get run performance metrics
The agent pulls aggregated performance data (latency, error rates, throughput) for a completed test run.

### Audit service level objectives (SLOs)
The agent retrieves detailed threshold evaluation results, verifying if the application met its predefined performance requirements.

### Monitor run status
The agent checks the status of ongoing test runs, reporting state transitions like QUEUED, RUNNING, or FINISHED.

## Use Cases

### The Post-Deployment Smoke Check
A developer pushes a new API endpoint. They ask their agent to 'Start a new test run for the Checkout Flow.' The agent uses `start_test_run`. After the run finishes, the developer immediately asks for 'the performance metrics for the last run.' The agent calls `get_run_metrics`, returning average latency and failure rates. The developer verifies the change didn't introduce regressions, solving the problem in minutes without touching a dashboard.

### Auditing Service Reliability
The QA team needs to know if the payment gateway passed its compliance checks. They ask the agent to 'Check the threshold evaluation for the main transaction test.' The agent calls `get_run_thresholds`, confirming that the failure rate never exceeded the mandated 0.1%. The team gets verifiable proof of compliance, which is much faster than manual reporting.

### Finding the Right Test Script
A new SRE joins the team and needs to know what load tests are available. They ask the agent to 'List all load tests in the Inventory service.' The agent calls `list_tests` and `list_projects`, giving the SRE a clear map of existing test assets and where they live, letting them get started instantly.

### Quickly Triaging a Failure
A run fails and the team needs to figure out why. They ask the agent to 'Get the details for the run that failed 15 minutes ago.' The agent calls `get_run` using the run ID, providing the full execution context. This allows the team to quickly distinguish between a configuration error and an actual performance degradation.

## Benefits

- **Analyze Metrics Instantly:** Instead of digging through dashboards, use `get_run_metrics` to pull aggregated data—average response time, P95 latency, error rates—for any completed run. You get the numbers immediately.
- **Verify SLO Compliance:** Need to know if your app hit its performance targets? `get_run_thresholds` pulls the detailed evaluation results. You confirm if your service meets specific SLOs against defined requirements.
- **Manage the Pipeline:** Use `list_tests` and `list_projects` to get a full inventory of every test and project in your account. It lets you know what tests exist before you even start building a run.
- **Control Resources:** Start a test run with `start_test_run` and, if things go sideways, use `stop_test_run` to kill it immediately. This prevents runaway tests from burning unnecessary k6 Cloud compute time.
- **Audit History:** Use `list_runs` to see a quick summary of all test executions—IDs, status (QUEUED/RUNNING/FINISHED), and duration—allowing you to track historical performance trends.
- **Deep Dive Debugging:** If a run fails, you can use `get_run` to get the full context and details of that specific execution, helping you pinpoint exactly where the failure happened.

## How It Works

The bottom line is, your agent uses your API token to talk directly to k6 Cloud, letting you manage the entire performance testing process through simple conversation.

1. Subscribe to the server and provide your k6 Cloud API Token.
2. Your AI client connects to the MCP endpoint and asks for a test run status or metric.
3. The agent calls the appropriate tool (e.g., `list_runs` or `get_run_metrics`) and returns the structured data.

## Frequently Asked Questions

**How do I list all my load tests using the list_tests tool?**
The agent calls `list_tests` and returns a list of all available load tests. This list includes the test name, its ID, and the status of its last run, helping you quickly map your entire test suite.

**What is the difference between get_run_metrics and get_run_thresholds?**
Metrics show raw performance data—things like average response time, P95 latency, and total iterations. Thresholds check if that raw data met your *required* standard, telling you if you passed or failed the SLO.

**Can I stop a running test using the stop_test_run tool?**
Yes. The agent calls `stop_test_run` and immediately sends the stop command to k6 Cloud. This is crucial for managing resources and preventing runaway tests from draining compute power.

**Do I need to know the run ID to get_run_metrics?**
Yes. You must provide the specific run ID to `get_run_metrics` so the agent knows exactly which test execution's data you want to analyze.

**How do I list all available organizations using the list_organizations tool?**
The `list_organizations` tool returns organization names, IDs, and member counts. You use this first to see which environments are available before managing tests.

**What is the purpose of the `start_test_run` tool?**
The `start_test_run` tool initiates a new k6 Cloud test run and returns the active run ID. This ID lets you track the test's status and monitor its progress.

**Can I check the status of a test run using the list_runs tool?**
Yes, `list_runs` returns run IDs, status states (QUEUED/RUNNING/FINISHED/ABORTED), VUs, durations, and timestamps. This helps you track the test's lifecycle at a glance.

**How do I get detailed information about a specific test using the get_test tool?**
The `get_test` tool retrieves the full details of a specific k6 test, including its script and configuration. You can use this to audit the test setup before running it.

**Can I see if a load test passed its performance thresholds using my agent?**
Yes. Use the `get_run_thresholds` tool with a specific Run ID. Your agent will retrieve the final evaluation for all defined thresholds in the script, indicating which specific SLOs passed or failed.

**How do I start a new k6 Cloud test run through a conversation?**
Use the `start_test_run` tool by providing the Test ID. Your agent will trigger the execution on k6 Cloud infrastructure and return an active Run ID that you can use to track real-time progress.

**Can my agent retrieve the raw performance metrics for a completed run?**
Absolutely. The `get_run_metrics` tool allows your agent to aggregate data like `http_req_duration`, error counts, and total iterations, providing a rapid summary of your application's behavior under load.