Random Number

Production-ready MCP server that provides LLMs with essential random generation abilities, built entirely on Python's standard library.

python

46

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "zazencodes-random-number-mcp": {
      "command": "uvx",
      "args": [
        "random-number-mcp"
      ]
    }
  }
}

You have a compact, high‑quality random number MCP server that exposes Python’s standard and cryptographically secure random utilities as MCP endpoints. Use it to generate random integers, floats, weighted selections, shuffles, and secure tokens from your applications, scripts, or services with simple MCP calls and consistent interfaces.

How to use

You will access the random number MCP server through your MCP client, sending requests that specify the function name and arguments. Use the provided tools to generate numbers, selections, and tokens in your workflows, tests, simulations, or security‑sensitive tasks. Each operation returns the corresponding value based on the parameters you supply.

How to install

Prerequisites: install Python 3.10+ and the uvx package manager on your system.

Step 1: Install the MCP client tooling (uvx) if you have not already.

Step 2: Clone the MCP server repository and navigate into it.

# Clone the repository
git clone https://github.com/example/random-number-mcp
cd random-number-mcp

# Install dependencies
uv sync --dev

# Run tests
uv run pytest

# Run linting
uv run ruff check --fix
uv run ruff format

# Type checking
uv run mypy src/

Additional notes

The MCP server provides both standard pseudorandom and cryptographically secure functions. Standard functions are fast and suitable for simulations and non‑security critical tasks, while secure functions use the Python secrets module for cryptographic quality randomness.

Security, testing, and usage tips

Security: Use secure_token_hex and secure_random_int only when cryptographic strength is required. For general randomness, the standard functions are faster and sufficient.

Testing with MCP Inspector: you can explore and develop locally by running the inspector against your MCP server to verify behavior and endpoints.

Available tools

random_int

Generate a random integer between low and high (inclusive) using the Python random.randint() function.

random_float

Generate a random float between low and high using the Python random.uniform() function.

random_choices

Select k items from a population with optional weights, using Python's random.choices().

random_shuffle

Return a new list with items shuffled, implemented via Python's random.sample().

random_sample

Choose k unique items from a population without replacement, using Python's random.sample().

secure_token_hex

Generate a cryptographically secure hex token using Python's secrets.token_hex().

secure_random_int

Generate a cryptographically secure random integer below an upper bound using secrets.randbelow().