LoadLab MCP server
Commit Nov 4, 2026A self-hosted load-testing platform that uses k6 to model user journeys and allows AI agents to draft and analyze performance tests via MCP.
Also known as sharkpaw/LoadLab
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- Apache-2.0
What is LoadLab MCP?
LoadLab is a self-hosted load-testing platform that uses k6 to model user journeys and allows AI agents to draft and analyze performance tests via MCP.
Summary generated from the project's README
About LoadLab MCP server
Modeling real user journeys to determine how much traffic a website can handle is what LoadLab enables for developers and QA teams. This self-hosted platform uses k6 to execute performance tests, ranging from simple smoke tests to complex breakpoint tests that automatically find a site's maximum capacity. Users can build visual workflows involving page interactions, API requests, and simulated thinking time, or even import HAR files to convert browser recordings into test scripts.
Integration with AI agents via the Model Context Protocol allows tools like Claude, Gemini, or Cursor to inspect sites, draft test plans, and analyze results. These agents create drafts that users review before execution. The system is deployed using Docker Compose or Coolify and supports distributed runs across multiple workers to prevent the load generator from becoming a bottleneck. It provides live monitoring of metrics like p95 latency and error rates, alongside a historical benchmark for every registered site.
What you can do with it
- 1Drafting automated performance workflowsAsk an AI agent to inspect a homepage and create a workflow that simulates users browsing products and signing in.
- 2Finding maximum site capacityRun a breakpoint test that increases load until specific performance thresholds are crossed to identify the breaking point.
- 3Comparing historical performance dataUse an AI client to analyze recent stress tests and identify which specific step in a user journey has slowed down.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
SERVICE_HEX_64_AUTHSERVICE_PASSWORD_ADMINSERVICE_PASSWORD_POSTGRES
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesharkpaw/loadlab is public and reachablegithub.com/sharkpaw/loadlab ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/sharkpaw/loadlab ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubEnglish · Türkçe
LoadLab
Know how much traffic your site can take. A self-hosted load-testing platform built on k6: model real user journeys, run them at any scale, watch results live and keep a performance history for every site. AI agents can also draft and analyse tests for you over MCP.
Features · Screenshots · Quick start · Deploy on Coolify · MCP · Contributing
Why LoadLab?
k6 is a great engine, but a script per test and a terminal full of numbers don't scale to a team or to a dozen sites. LoadLab puts a product around it:
- 🧭 Real user journeys, not URL lists. Build flows like visit → open a random product → 30% sign in → 10% buy in a visual editor, with probabilities, loops, variables and shared modules.
- 📈 Live results you can act on. Watch users, requests/s, p50/p95/p99 and errors second by second. You can stop or force-stop any test.
- 💥 Find the breaking point. A breakpoint test keeps raising the load and stops itself when p95 or the error rate crosses your limit. It then reports the highest healthy throughput.
- 🗂️ A benchmark history per site. Compare runs, mark a baseline and track p95 and capacity over time to catch regressions.
- 🤖 Built for AI agents (MCP). Claude, Gemini, ChatGPT, Cursor or any other MCP client can inspect your site, draft workflows and test plans, debug them and read the results. You review the draft and press Start.
- 🔒 Secure by default. Better Auth with 2FA, rate-limited sign-in, no public sign-up, and tests that can only reach the hosts you registered.
- 🧮 Know your own footprint. See LoadLab's CPU, memory, database and disk usage, with a warning when the load generator, not your site, is the bottleneck.
- 🌐 Multilingual dashboard: English and Turkish, switchable at any time.
Features
Workflows
- Visual flow editor with step types:
page(HTML plus its CSS/JS/images),request(any API call with JSON/form/raw body),think(user pause),set(variables),group(probability + repeat) andinclude(shared module, e.g. Sign in). - Checks (status, body contains, JSON path, max duration, header) and extraction from JSON, HTML (CSS selectors), regex, headers or cookies. Each can pick the first, a random or every match.
- Templates such as
{{productId}},{{data.users.email}}(per-user datasets),{{$randomInt 1 10}},{{$uuid}}and{{$randomItem list}}. - Debug run: 1 user, 1 iteration, with status, timing, extracted variables and a response preview for every step.
- HAR import: record yourself in the browser and get a draft workflow, with pauses turned into think time.
- Browser workflows: switch a workflow to Browser (Chromium) and script a real page with
goto,click,fill,select,press,waitFor,expectandreadsteps. A plan can mix them with HTTP workflows: the HTTP flows make the load while a few browser users (Browser VUs) measure what visitors see. Requests to hosts outside the site's allowlist (analytics, ad scripts) are blocked and listed in the run's warnings. Needs a worker with Chromium (BROWSER_WORKER_REPLICAS). - Version history, JSON view, built-in DSL guide and a page inspector that lists a page's links and forms.
Test plans and profiles
Mix several workflows by weight and pick a profile:
| Profile | Use it for |
|---|---|
| Smoke | Does the flow work at all? |
| Constant users / Constant rate | Steady load by concurrency or by arrivals per second |
| Ramp-up · Stress · Spike | Staged load shapes (editable stages, live preview) |
| Soak | Hours of steady load: leaks and slow degradation |
| Breakpoint | Ramps the arrival rate until p95 or errors cross your limit, then reports capacity |
Plans also get pass/fail thresholds (p95, p99, error rate, check rate), auto-stop rules and optional cron schedules for nightly benchmarks.
Distributed runs: set Workers in a plan's advanced options to split one test across several workers when a single worker's CPU is the limit. Each worker runs an equal share of the VUs and rate (k6 execution segments), all of them start from a paused state at the same moment, and the lead worker merges their results into one run: the same live charts, per-step table and summary, plus a per-worker table. A distributed test waits in the queue until enough workers are free; if a worker drops out mid-test, the run stops and keeps what was measured.
Runs
- Live charts over Server-Sent Events, a per-step latency table and status codes, plus a breakdown of where users dropped out.
- Stop (graceful) and Force stop, queue cancellation and re-run.
- Compare any two runs, or a run against the site's baseline.
Screenshots
| Overview | Workflow editor |
|---|---|
| Breakpoint result | Test plan |
| Site benchmark | System resources |
| Sign in | Settings & MCP |
Quick start
Requirements: Docker with Compose v2.
git clone https://github.com/sharkpaw/LoadLab.git && cd LoadLab
cp .env.example .env
Fill in the three secrets in .env, for example with openssl rand -hex 32:
SERVICE_PASSWORD_POSTGRES=... # database password
SERVICE_HEX_64_AUTH=... # session secret (64 hex chars)
SERVICE_PASSWORD_ADMIN=... # first admin password, min. 10 characters
docker compose up -d --build
Open http://localhost:8080 and sign in as admin@example.com (or your ADMIN_EMAIL). Then:
- Add a site. Enter the base URL of a system you own, plus any extra hosts it may call.
- Create a workflow from a template or a HAR file, and check it with Debug run.
- Create a test plan. Pick workflows, a profile and thresholds, then press Start.
⚠️ Only test systems you own or are explicitly allowed to test. LoadLab generates real traffic.
Deploy on Coolify
docker-compose.yml follows Coolify's conventions: expose instead of ports, and auto-generated SERVICE_* secrets.
- New Resource → Git repository → Docker Compose, pointing at this repository.
- Assign a domain to the loadlab service:
https://loadlab.example.com:8080. The:8080is the internal port the proxy routes to. - Set
ADMIN_EMAIL. Coolify generatesSERVICE_PASSWORD_POSTGRES,SERVICE_HEX_64_AUTHandSERVICE_PASSWORD_ADMIN; your first password isSERVICE_PASSWORD_ADMIN. - Deploy, sign in, then change your password and enable 2FA under Settings.
Prebuilt multi-arch images are published to ghcr.io/sharkpaw/loadlab for every release.
Use it with AI agents (MCP)
LoadLab speaks the open Model Context Protocol, so it works with any MCP client that supports Streamable HTTP: Claude, Gemini CLI, ChatGPT, Codex, Cursor, VS Code, Windsurf and others. Pick one of two ways to sign in. Settings & MCP shows copy-ready setup for both.
OAuth (recommended): add just the server URL. The client discovers LoadLab's OAuth 2.1 server, opens the sign-in page in your browser, and you approve it on a consent screen. Behind this are dynamic client registration and PKCE, and tokens are bound to your /mcp resource.
claude mcp add --transport http loadlab https://loadlab.example.com/mcp
gemini mcp add --transport http loadlab https://loadlab.example.com/mcp
codex mcp add loadlab --url https://loadlab.example.com/mcp
For ChatGPT or Claude.ai connectors, paste https://loadlab.example.com/mcp as the server URL.
API key: for clients without OAuth, or for scripts. Create a key under Settings & MCP:
claude mcp add --transport http loadlab https://loadlab.example.com/mcp --header "Authorization: Bearer ll_..."
Clients that can neither do OAuth nor send headers can use https://loadlab.example.com/mcp?token=ll_.... Keep that URL private, because the key is part of it. OAuth needs an HTTPS PUBLIC_URL (plain HTTP only on localhost); turn it off with MCP_OAUTH=false.
LoadLab exposes 25 tools: inspect a page, create, update or debug workflows, draft test plans, read run results and time series, compare runs, view site benchmarks and check system status. Everything an agent creates arrives as a draft under Drafts awaiting review. Letting MCP start tests directly requires MCP_ALLOW_RUN=true, which is off by default.
Example prompts:
- "Inspect my shop's home page and draft a workflow that opens a random product, where 30% sign in and 10% add to cart. Verify it with a debug run."
- "Draft a breakpoint test with these workflows in a 70/30 mix that stops at p95 1 s or 2% errors."
- "Compare the last two stress tests. Which step got slower?"
How it works
Browser ─────▶ api (Bun + Fastify) ─ dashboard · REST · SSE · /mcp · Better Auth
AI agent (MCP) ▶ │ queue: Postgres (SKIP LOCKED) + Redis wake-up
▼
worker ×N (Bun) ── k6 + runner.js ─────────▶ your site
│ k6 JSON output (FIFO) → per-second buckets, per-step histograms
▼
Postgres + Drizzle (sites, workflows, plans, runs, metrics, auth)
Redis (live stream, stop signals, session cache, rate limits)
- k6 runs one generic script (
server/k6/runner.js) that interprets the workflow JSON. No code is generated per test. - Each worker runs one test at a time for clean measurements. Scale out with
WORKER_REPLICAS: more tests in parallel, or one test split across workers (Workers in the plan). Workers on other machines can join as long as they reach the same Postgres and Redis. - The worker tracks k6's own CPU and warns when the load generator saturates or when iterations are dropped.
Security
- Authentication: Better Auth with email + password (min. 10 chars), TOTP two-factor with backup codes, session list and remote sign-out, in-app password change.
- Forgot password: reset links are valid for 30 minutes and work only once, and resetting signs out every session and sends a "password changed" notice. The form never reveals whether an e-mail exists. Without SMTP, the link is printed to the API log for an administrator.
- Hardening: public sign-up is disabled, and sign-in, 2FA and password-reset attempts are rate-limited in Redis. State-changing requests get an origin check, and deleting a user revokes their cached sessions too. CSP, HSTS (on HTTPS) and
X-Frame-Optionsare set. - Target safety: tests can only reach the site's base URL host and its
allowedHosts. This is enforced both when a plan is compiled and inside k6 at runtime. VUs, rate and duration are capped byMAX_VUS,MAX_RATEandMAX_DURATION_SEC. - MCP access: OAuth 2.1 with PKCE, explicit consent and tokens bound to the
/mcpresource, or revocable API keys stored only as SHA-256 hashes.
Admin CLI (server terminal)
For when nobody can sign in, or someone lost their phone:
docker compose exec loadlab bun src/cli.ts users
docker compose exec loadlab bun src/cli.ts reset-password admin@example.com # prints a new random password
docker compose exec loadlab bun src/cli.ts disable-2fa user@example.com
docker compose exec loadlab bun src/cli.ts revoke-sessions user@example.com
docker compose exec loadlab bun src/cli.ts create-user ops@example.com --name Ops
On Coolify, use the loadlab container's terminal and run the same bun src/cli.ts … commands.
Report vulnerabilities privately; see SECURITY.md.
Configuration
All variables are validated at startup with t3-env and zod. If a required one is missing or invalid, the container exits and lists every problem instead of starting half-configured.
| Variable | Default | Description |
|---|---|---|
SERVICE_PASSWORD_POSTGRES |
— (required) | Postgres password (generated by Coolify) |
SERVICE_HEX_64_AUTH |
— (required) | Better Auth secret (generated by Coolify) |
SERVICE_PASSWORD_ADMIN |
— (required) | First admin password; only used while there are no users |
ADMIN_EMAIL |
admin@example.com |
First admin's email |
PUBLIC_URL |
SERVICE_URL_LOADLAB |
Public URL of the dashboard (cookies, origin checks, MCP links) |
TRUSTED_ORIGINS |
— | Extra dashboard origins, comma-separated |
TRUST_PROXY_HOPS |
1 |
Reverse proxies in front of the API (0 if exposed directly) |
WORKER_REPLICAS |
1 |
Number of workers: tests that can run in parallel, and the most a single test can be split across |
BROWSER_WORKER_REPLICAS |
0 |
Workers with Chromium for browser workflows (worker-browser service; the image is about 1 GB larger, each browser VU needs about half a CPU core and 200 MB) |
MAX_BROWSER_VUS |
5 |
Most browser VUs a test may use |
MAX_VUS / MAX_RATE / MAX_DURATION_SEC |
5000 / 20000 / 14400 | Safety caps |
MCP_ALLOW_RUN |
false |
Allow MCP clients to start tests |
MCP_ALLOW_DEBUG |
true |
Allow MCP clients to start 1-iteration debug runs |
MCP_OAUTH |
true |
OAuth 2.1 sign-in for MCP clients (needs an HTTPS PUBLIC_URL or localhost) |
SMTP_HOST / SMTP_PORT / SMTP_SECURE / SMTP_USER / SMTP_PASS / SMTP_FROM |
— / 587 / false | Optional SMTP for password-reset mail. Without it, reset links go to the API log (docker compose logs loadlab | grep "reset link") |
TZ |
UTC |
Time zone (cron schedules) |
Development
cd server && bun install && bun run typecheck && bun run test
cd web && bun install && bun run dev # http://localhost:5173, proxies to :8080
- Stack: Bun · Fastify 5 · Drizzle ORM (Postgres) · Redis · Better Auth · React 19 · Vite · Tailwind 4 · Recharts · k6.
- Database:
server/src/db/schema.tsis the single source of truth. After changing it, runbun run db:generate --name <change>. Migrations apply automatically on startup. - Translations: UI text goes through
t('…'), andbun run i18n:checkmakes sure every string has a Turkish entry. - Tests: unit tests run with
bun run test. CI also boots the whole stack in Docker and runs an end-to-end smoke test (server/test/e2e/smoke.ts) with real k6 runs.
Project layout and conventions: AGENTS.md.
Roadmap
| ✅ | Visual workflow editor, shared modules, HAR import, debug runs |
| ✅ | Load profiles including breakpoint / capacity detection |
| ✅ | Live charts, stop / force stop, run comparison, site benchmarks |
| ✅ | MCP server for drafting and analysing tests with any AI agent |
| ✅ | Better Auth with 2FA, password reset (SMTP or log) and an admin CLI |
| ✅ | English and Turkish UI |
| ✅ | Coolify-ready compose, multi-arch images, CI with end-to-end tests |
| ✅ | Distributed runs (one test across several workers) |
| ⬜ | Browser-level steps (k6 browser) for front-end metrics |
| ⬜ | Notifications (Slack / e-mail / webhooks) on threshold failures |
| ⬜ | More languages (contributions welcome) |
Contributing
Contributions are welcome! See CONTRIBUTING.md.
- 🐞 Report a bug
- ✨ Request a feature
- 🔧 Fork, branch and open a pull request to
main. CI runs type checks, unit tests, the translation check and a full Docker + k6 end-to-end test.
License
LoadLab is released under the Apache License 2.0.
The Docker image bundles the unmodified k6 binary by Grafana Labs, which is licensed under AGPL-3.0 and runs as a separate program; see NOTICE. LoadLab is not affiliated with Grafana Labs.
LoadLab MCP questions
Can AI agents create tests for me?
Yes, AI agents using MCP can inspect your site, draft workflows and test plans, debug them, and read the results.
Can I run tests using a real browser?
Yes, you can switch a workflow to Browser (Chromium) to script real page interactions like clicking and filling forms.