locust

This MCP server enables running Locust load tests from an AI-assisted environment via the Model Context Protocol. It exposes a run_locust tool that lets you start a Locust test with configurable options such as headless versus UI mode, target host, runtime, number of users, and spawn rate. You can initiate tests by creating a Locust test script (for example hello.py) and then issuing a run_locust call through the MCP client. The server accepts both headless load tests for automation and a UI mode for interactive exploration, making it suitable for both automated pipelines and ad-hoc testing. To use it, prepare your Locust script, configure your test parameters (host, runtime, users, spawn_rate), and then instruct the MCP client to run the test via the provided API, which will launch Locust with the specified options and stream real-time output.

Prerequisites:

• Python 3.13 or higher
• uv package manager (install instructions: https://github.com/astral-sh/uv)

Installation steps:

1. Clone the repository

git clone https://github.com/qainsights/locust-mcp-server.git

2. Install dependencies

uv pip install -r requirements.txt

3. (Optional) Set up environment variables by creating a .env file in the project root, for example:

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

4. Run the MCP server using your preferred MCP client and ensure the mcp_config points to the uv command as shown in the config section.

Tips and notes:

• Ensure your Locust test script (e.g., hello.py) is accessible to the MCP server, typically within the project directory configured in the MCP client.
• The LOCUST_RUN_TIME value can be a duration like '10s', '30s', '1m', or '5m'.
• If you run in UI mode, Locust will start with a web interface on the configured host; in headless mode, tests run in the background and emit real-time stats via the MCP channel.
• You can customize Locust parameters by adjusting the environment variables LOCUST_HOST, LOCUST_USERS, LOCUST_SPAWN_RATE, and LOCUST_RUN_TIME as defaults, or override them per run via the run_locust API.
• Common issues: ensure Python 3.13+ compatibility with Locust versions and that the uv tool is properly installed and accessible in PATH.
• If the MCP server cannot locate locust_server.py, verify the --directory path and the file name used in the run command.