Random MCP

A local Python MCP server for pseudorandom sampling. Uses the official MCP Python SDK.

Install and run

Requires Python 3.10 or newer. From this directory:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/random-mcp

The server communicates over stdio and waits for an MCP client. It also supports python -m random_mcp from the environment where it is installed. On Windows, use .venv\Scripts\python.exe and .venv\Scripts\random-mcp.exe.

Configure your MCP host with an absolute path to the installed command:

{
  "mcpServers": {
    "random": {
      "command": "/absolute/path/to/random-mcp/.venv/bin/random-mcp",
      "args": []
    }
  }
}

Related MCP server: MCP Dice Roller

Tools

• random_number() returns {"value": 0.375}: one uniform float in [0, 1).

• random_interval(minimum, maximum, kind="float") returns {"value": ...}. Choose "integer" for whole numbers, with both endpoints included. Float sampling follows Python's random.uniform; rounding can include the upper endpoint. Equal bounds return that value. Reversed bounds, non-finite values, fractional integer bounds, and non-finite sampling results produce tool errors.

• random_normal(mean=0, standard_deviation=1) returns {"value": ...} from a normal distribution. Both parameters must be finite; standard deviation must be positive. Non-finite results produce tool errors.

Values shown are examples. Sampling uses Python's standard pseudorandom generator, without public seed parameters. Each number call returns one sample.

Dice

roll_dice(expression, detail="auto") accepts NdM, such as 1d10, 2d10, or 100d10, and sums such as 1d10 + 2d100 + 5d4. Each die is sampled independently from 1 through M, inclusive. Whitespace, uppercase D, and leading zeros are accepted. Counts and sides must be positive integers. Only addition is supported: modifiers, subtraction, multiplication, and parentheses are rejected. Terms remain in input order.

• auto: include individual rolls for up to 100 total dice; use compact above 100.

• full: always include individual rolls.

• compact: return aggregates without individual rolls or roll arrays in memory.

For example, roll_dice("1000d4") returns this shape (totals vary):

{
  "expression": "1000d4",
  "detail": "compact",
  "total_dice": 1000,
  "total": 2500,
  "terms": [{"count": 1000, "sides": 4, "subtotal": 2500}]
}

Full mode adds a rolls array to each term. Auto considers the total count across all terms. Limits are 10,000 total dice, 100 terms, 1,000,000 sides per die, and 10,000 expression characters. Invalid requests return tool errors before any dice are rolled.

Development

Install the development tools with python -m pip install -e '.[dev]' using the virtual environment's Python. Run all checks before committing:

.venv/bin/python -m ruff check .
.venv/bin/python -m ruff format --check .
.venv/bin/python -m mypy
.venv/bin/python -m pytest

Apply automatic lint fixes and formatting with:

.venv/bin/python -m ruff check --fix .
.venv/bin/python -m ruff format .

Ruff checks application code and tests for common errors, import ordering, and consistent formatting, with Python 3.10 as the target. Mypy runs in strict mode on src; pytest covers sampling, dice parsing, MCP validation, and stdio calls. Tool settings live in pyproject.toml.

Features are delivered in five commits: uniform sampling, intervals, normal sampling, simple dice, then compound dice. Each stage includes tests and docs.