Overview

This project provides a Model Context Protocol (MCP) server that exposes Locust load-testing capabilities to MCP-enabled developer tools and AI agents. The server lets you start, configure, and monitor Locust test runs programmatically from MCP clients (for example: Claude Desktop, Cursor, Windsurf), enabling tighter integration of performance testing into AI-assisted development workflows and conversational tooling.

By running Locust through an MCP server you can: start headless load tests from an LLM-driven agent, receive real-time execution output, and switch between headless and UI modes without manual server interaction. The implementation supports standard Locust features (HTTP/HTTPS, custom task scenarios) and exposes a compact API to control run parameters such as target host, user count, spawn rate and runtime.

Features

Model Context Protocol (MCP) server to run Locust test scripts programmatically
Headless and UI modes supported
Configurable run parameters: users, spawn rate, runtime, host
Real-time test output streaming to MCP clients
HTTP and HTTPS load targets supported
Support for custom Locust task scripts and scenarios
Simple API function for starting tests from MCP-enabled tools

Prerequisites

Python 3.13 or newer
uv package manager (https://github.com/astral-sh/uv)
Locust (installed via requirements in the repo)

Installation / Configuration

Clone the repository and install dependencies:

git clone https://github.com/QAInsights/locust-mcp-server.git
cd locust-mcp-server
uv pip install -r requirements.txt

(Optional) Configure environment variables by creating a .env file in the project root:

# .env
LOCUST_HOST=http://localhost:8089
LOCUST_USERS=3
LOCUST_SPAWN_RATE=1
LOCUST_RUN_TIME=10s

Run the MCP server via uv (example using the repo directory):

uv run locust_server.py

Or configure an MCP client to launch the server directly (example MCP client configuration):

{
  "mcpServers": {
    "locust": {
      "command": "/Users/you/.local/bin/uv",
      "args": [
        "--directory",
        "/path/to/locust-mcp-server",
        "run",
        "locust_server.py"
      ]
    }
  }
}

Available Tools

The MCP server exposes a simple tool for running Locust tests:

run_locust( test_file: str, headless: bool = True, host: str = “http://localhost:8089”, runtime: str = “10s”, users: int = 3, spawn_rate: int = 1 )

Parameter reference:

Parameter	Type	Default	Description
test_file	string	—	Path to your Locust test script
headless	boolean	true	Run in headless mode (true) or open Locust web UI (false)
host	string	http://localhost:8089	Target host to test
runtime	string	10s	Duration (e.g., “30s”, “1m”)
users	int	3	Number of concurrent simulated users
spawn_rate	int	1	Users spawned per second

The server streams logs and basic run metrics back to the MCP client so an LLM or UI can present real-time progress.

Example Locust Test Script

Save the following as hello.py and pass its path to run_locust:

from locust import HttpUser, task, between

class QuickstartUser(HttpUser):
    wait_time = between(1, 5)

    @task
    def hello_world(self):
        self.client.get("/hello")
        self.client.get("/world")

    @task(3)
    def view_items(self):
        for item_id in range(10):
            self.client.get(f"/item?id={item_id}", name="/item")

Start a headless test via the MCP client by calling run_locust with the path to hello.py and desired parameters.

Use Cases

LLM-driven load testing: Ask your assistant to “run a Locust test for hello.py for 30s with 10 users” and receive live feedback and a final summary.
CI / PR validation: Integrate an MCP-enabled agent into CI pipelines to run quick smoke-load tests when an API endpoint or performance-relevant change is detected.
Debugging with realistic traffic: Run scenario scripts that reproduce user behavior and stream results to a dev environment where an LLM can help interpret error traces or latency spikes.
Exploratory performance analysis: Quickly switch between UI and headless modes to visualize metrics in the Locust web UI or capture machine-readable outputs for downstream processing.

Notes & Tips

The server relies on Locust for behavior definition—create or reuse standard Locust task files.
Use the .env overrides to set sane defaults for local development.
When using the MCP client, ensure file paths passed to run_locust are accessible from the MCP server process (paths are relative to the server working directory if using uv –directory).
The project is MIT licensed (see LICENSE in the repository) and accepts contributions via PRs on GitHub: https://github.com/QAInsights/locust-mcp-server

Locust MCP Server for AI Development Load Testing