MCP Server

dbworkload includes an optional Model Context Protocol (MCP) server that helps AI coding agents write and validate workload classes.

The server runs over stdio and exposes:

• dbworkload://server/info: a resource with readiness and capability details.
• dbworkload://docs/skills: a resource with workload authoring rules.
• get_server_info: a tool that reports server readiness and exposed features.
• get_authoring_rules: a tool that returns the same authoring guidance.
• dry_run_workload: a tool that runs one dbworkload iteration against a target database URI.
• run_workload: a tool that runs dbworkload run with the full set of CLI options.
• generate_data_seed_blueprint: a tool that creates a JSON-compatible data seeding blueprint from raw DDL text.
• generate_csv_files: a tool that writes CSV/TSV seed files from a data seeding blueprint and returns generated file paths.

Install

Install pipx if it is not already available.

On macOS with Homebrew:

brew install pipx
pipx ensurepath

Then install dbworkload with the optional MCP dependency:

pipx install "dbworkload[mcp]"

Test the install

Confirm that the command is available:

dbworkload-mcp-server --info

Expected output starts with:

dbworkload MCP server is installed and ready.

The output also lists the resources and tools exposed by the server.

MCP client configuration

Add the server to an MCP-compatible client such as Claude Desktop, Cursor, Windsurf, or VS Code with MCP support.

{
  "mcpServers": {
    "dbworkload": {
      "command": "dbworkload-mcp-server"
    }
  }
}

After adding the configuration, restart the client and ask it to call get_server_info. A working setup should report that the server is installed and ready.

Expected agent flow

Once registered, an AI agent can:

1. Call get_server_info to confirm the server is available.
2. Read dbworkload://docs/skills to learn the workload class contract.
3. Generate or edit a workload Python file in the user's workspace.
4. Call dry_run_workload with the workload path and database URI.
5. Use the returned stdout, stderr, and exit code to fix the workload and retry.
6. Call run_workload with the desired run options.

Generating a data seed blueprint

generate_data_seed_blueprint accepts raw DDL text and returns a JSON-compatible data seeding blueprint. The agent can then inspect, refine, or write that blueprint to YAML/JSON as needed.

{
  "ddl": "CREATE TABLE accounts (id BIGINT PRIMARY KEY, balance DECIMAL(15, 2));"
}

Example response shape:

{
  "ok": true,
  "format": "json",
  "blueprint": {
    "accounts": [
      {
        "count": 100,
        "sort-by": [],
        "columns": {
          "id": {
            "type": "integer"
          },
          "balance": {
            "type": "float"
          }
        }
      }
    ]
  }
}

The tool does not read or write files. File operations are left to the agent.

Generating CSV files

generate_csv_files accepts a data seed blueprint object, writes CSV/TSV files to output_dir, and returns generated file paths plus database import statements.

{
  "seed_blueprint": {
    "accounts": [
      {
        "count": 100,
        "sort-by": ["id"],
        "columns": {
          "id": {
            "type": "sequence"
          },
          "balance": {
            "type": "float",
            "args": {
              "min": 0,
              "max": 10000,
              "round": 2
            }
          }
        }
      }
    ]
  },
  "output_dir": "seed/accounts",
  "procs": 1,
  "csv_max_rows": 100000,
  "delimiter": "\t",
  "compression": null
}

Example response shape:

{
  "ok": true,
  "output_dir": "seed/accounts",
  "file_count": 1,
  "files": [
    "seed/accounts/accounts.0_0_0.tsv"
  ],
  "import_statements": {
    "accounts": [
      "IMPORT INTO accounts ..."
    ]
  }
}

If output_dir already exists, the tool renames it to a timestamped backup directory before writing the new files.

Using run_workload

When using the CLI directly, run options are passed as flags:

dbworkload run \
  --workload workloads/postgres/hello.py \
  --uri "postgresql://user:password@localhost:5432/postgres" \
  --concurrency 4 \
  --iterations 1000 \
  --ramp 10 \
  --quiet

Through MCP, an agent sends the same values as named tool arguments:

{
  "workload_path": "workloads/postgres/hello.py",
  "db_uri": "postgresql://user:password@localhost:5432/postgres",
  "concurrency": 4,
  "iterations": 1000,
  "ramp": 10,
  "quiet": true
}

In chat, you can ask for the same thing in plain language:

Use the dbworkload MCP server to run workloads/postgres/hello.py against
postgresql://user:password@localhost:5432/postgres with concurrency 4,
1000 iterations, 10 seconds ramp, and quiet output.

Notes

dry_run_workload wraps the existing CLI command:

dbworkload run --workload <file> --uri <uri> --iterations 1 --quiet

run_workload wraps dbworkload run and accepts the same options as the CLI, plus timeout_seconds to bound the MCP tool call. To avoid accidental never-ending tool calls, run_workload requires iterations, duration, or schedule.

A database smoke-test tool can be added later if dbworkload grows a dedicated connection-check command.