Overview

This MCP (Model Context Protocol) server exposes a compact suite of random number utilities built on Python’s standard library. It provides both fast pseudorandom operations (for simulations, sampling, shuffling, and randomized UX) and cryptographically secure operations (for tokens, keys, and security-sensitive integers). The server is designed to be used by Claude Desktop or other MCP-compatible clients to supply deterministic-looking randomness where needed in agent workflows.

The utilities are intentionally small and focused: integer/float generation, sampling and weighted selection, list shuffling, and secure token/int generation. These cover common developer needs such as Monte Carlo simulations, A/B test shuffling, weighted portfolio sampling, and secure API token creation. Source and development instructions are available on GitHub: https://github.com/zazencodes/random-number-mcp

Features

Pseudorandom integers and floats (Python random module)
Weighted and unweighted sampling with or without replacement
Non-destructive list shuffling (returns a new list)
Cryptographically secure hex token generation (secrets.token_hex)
Cryptographically secure integer generation (secrets.randbelow)
Small API surface suitable for MCP clients and automation

Installation / Configuration

Prerequisites:

Python 3.10+
uv package manager (used in repository development and running MCP)

Clone and install for development:

git clone https://github.com/zazencodes/random-number-mcp
cd random-number-mcp

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest

# Build
uv build

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

Add an entry like:

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

Local development MCP client config (point to local directory):

{
  "mcpServers": {
    "random-number-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/random-number-mcp",
        "run",
        "random-number-mcp"
      ]
    }
  }
}

Available Tools

The server exposes a small set of functions. The table below maps tool names to their primary Python implementation.

Tool	Purpose	Python function
random_int	Random integer between bounds (inclusive)	random.randint
random_float	Random float in [low, high) or [low, high] depending on use	random.uniform
random_choices	Choose k items with replacement, optional weights	random.choices
random_sample	Choose k unique items without replacement	random.sample
random_shuffle	Return a new list with items randomly ordered	random.sample
secure_token_hex	Cryptographically secure hexadecimal token	secrets.token_hex
secure_random_int	Cryptographically secure integer in [0, upper_bound)	secrets.randbelow

Tool usage (MCP call format: JSON name + arguments)

random_int

{
  "name": "random_int",
  "arguments": { "low": 1, "high": 100 }
}

random_float

{
  "name": "random_float",
  "arguments": { "low": 0.0, "high": 1.0 }
}

random_choices (with weights)

{
  "name": "random_choices",
  "arguments": {
    "population": ["A", "B", "C"],
    "k": 3,
    "weights": [0.5, 0.3, 0.2]
  }
}

random_sample

{
  "name": "random_sample",
  "arguments": { "population": [1,2,3,4,5], "k": 2 }
}

random_shuffle

{
  "name": "random_shuffle",
  "arguments": { "items": ["x","y","z"] }
}

secure_token_hex

{
  "name": "secure_token_hex",
  "arguments": { "nbytes": 16 }
}

secure_random_int

{
  "name": "secure_random_int",
  "arguments": { "upper_bound": 1000 }
}

Use Cases

Monte Carlo simulations: Use random_float and random_int to drive stochastic simulations for risk modeling, pricing, or scenario analysis.
Portfolio sampling and weighting: Use random_choices with weights to model allocation scenarios where probabilities are non-uniform.
A/B testing and randomization: Use random_shuffle to create randomized sequences (non-destructive) or random_sample to select unique test cohorts.
Secure tokens and identifiers: Use secure_token_hex for issuing API keys, session tokens, or cryptographic identifiers that must be unpredictable.
One-time codes and nonce generation: Use secure_random_int for numeric OTPs or nonces where security is required.
Deterministic workflows (non-crypto): Use pseudorandom functions for reproducible demo data and UX flows where cryptographic strength is not required.

Security note: pseudorandom functions (random_*) are fast and adequate for simulations and non-sensitive randomness. For any security-sensitive generation (tokens, keys, OTPs), prefer secure_token_hex and secure_random_int from Python’s secrets module.

Additional Resources

Repository and source: https://github.com/zazencodes/random-number-mcp
Python docs: random and secrets modules
Development: uv package manager docs (used for running and packaging the MCP server)

This server is intentionally minimal and easy to integrate via MCP clients. Use the secure variants for any sensitive data, and prefer pseudorandom variants when performance and convenience are more important than cryptographic guarantees.

MCP Server Random Number Generation Utilities