Random Number MCP

What is Random Number MCP about?

Random Number MCP offers a set of tools that generate pseudorandom and cryptographically‑secure values directly from Python’s built‑in random and secrets modules. It exposes these capabilities as MCP tools, enabling LLMs to request numbers, selections, shuffles, or secure tokens without writing custom code.

How to use Random Number MCP?

Add the server to your MCP client configuration (Claude Desktop, FastMCP, etc.). Example JSON for Claude Desktop:

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

Invoke a tool by sending a JSON payload that matches the tool’s schema. Example for a random integer:

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

Receive the result from the MCP server in the standard MCP response format.

Key Features

Standard pseudorandom utilities (random_int, random_float, random_choices, random_shuffle, random_sample).
Cryptographically secure functions (secure_token_hex, secure_random_int).
Pure Python implementation – no external dependencies beyond the standard library.
Ready‑to‑run via uvx (or uv run) for quick local testing and production deployment.
Comprehensive documentation and demo video.

Use Cases

Game logic or simulations that need repeatable, fast random numbers.
Data augmentation pipelines requiring random sampling or shuffling.
Generation of secure tokens, API keys, or one‑time passwords.
LLM‑driven workflows where the model must request random outcomes without embedding code.
Testing frameworks that need deterministic or secure randomness.

FAQ

Q: Do I need any third‑party libraries? A: No. All functionality relies on Python’s built‑in random and secrets modules.

Q: How can I get cryptographically secure numbers? A: Use secure_random_int or secure_token_hex, which internally call secrets.randbelow and secrets.token_hex.

Q: Can I control the seed for reproducible results? A: The standard tools do not expose a seed parameter, but you can set the seed in your own code before invoking the MCP server if reproducibility is required.

Q: What Python version is required? A: Python 3.10 or newer.

Q: How do I run the server in development mode? A: Clone the repo, install uv, then run uv run random-number-mcp. For inspection use the MCP Inspector: npx @modelcontextprotocol/inspector uv run random-number-mcp.

Essential random number generation utilities from the Python standard library, including pseudorandom and cryptographically secure operations for integers, floats, weighted selections, list shuffling, and secure token generation.

📺 Demo Video

https://github.com/user-attachments/assets/303a441a-2b10-47e3-b2a5-c8b51840e362

🎲 Tools

Tool	Purpose	Python function
`random_int`	Generate random integers	`random.randint()`
`random_float`	Generate random floats	`random.uniform()`
`random_choices`	Choose items from a list (optional weights)	`random.choices()`
`random_shuffle`	Return a new list with items shuffled	`random.sample()`
`random_sample`	Choose k unique items from population	`random.sample()`
`secure_token_hex`	Generate cryptographically secure hex tokens	`secrets.token_hex()`
`secure_random_int`	Generate cryptographically secure integers	`secrets.randbelow()`

🔧 Setup

Claude Desktop

Add this to your Claude Desktop configuration file:

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

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

📋 Tool Reference

`random_int`

Generate a random integer between low and high (inclusive).

Parameters:

low (int): Lower bound (inclusive)
high (int): Upper bound (inclusive)

Example:

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

`random_float`

Generate a random float between low and high.

Parameters:

low (float, optional): Lower bound (default: 0.0)
high (float, optional): Upper bound (default: 1.0)

Example:

{
  "name": "random_float",
  "arguments": {
    "low": 0.5,
    "high": 2.5
  }
}

`random_choices`

Choose k items from a population with replacement, optionally weighted.

Parameters:

population (list): List of items to choose from
k (int, optional): Number of items to choose (default: 1)
weights (list, optional): Weights for each item (default: equal weights)

Example:

{
  "name": "random_choices",
  "arguments": {
    "population": ["red", "blue", "green", "yellow"],
    "k": 2,
    "weights": [0.4, 0.3, 0.2, 0.1]
  }
}

`random_shuffle`

Return a new list with items in random order.

Parameters:

items (list): List of items to shuffle

Example:

{
  "name": "random_shuffle",
  "arguments": {
    "items": [1, 2, 3, 4, 5]
  }
}

`random_sample`

Choose k unique items from population without replacement.

Parameters:

population (list): List of items to choose from
k (int): Number of items to choose

Example:

{
  "name": "random_sample",
  "arguments": {
    "population": ["a", "b", "c", "d", "e"],
    "k": 2
  }
}

`secure_token_hex`

Generate a cryptographically secure random hex token.

Parameters:

nbytes (int, optional): Number of random bytes (default: 32)

Example:

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

`secure_random_int`

Generate a cryptographically secure random integer below upper_bound.

Parameters:

upper_bound (int): Upper bound (exclusive)

Example:

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

🔒 Security Considerations

This package provides both standard pseudorandom functions (suitable for simulations, games, etc.) and cryptographically secure functions (suitable for tokens, keys, etc.):

Standard functions (random_int, random_float, random_choices, random_shuffle): Use Python's random module - fast but not cryptographically secure
Secure functions (secure_token_hex, secure_random_int): Use Python's secrets module - slower but cryptographically secure

🛠️ Development

Prerequisites

Python 3.10+
uv package manager

Setup

# 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/

MCP Client Config

{
  "mcpServers": {
    "random-number-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "<path_to_your_repo>/random-number-mcp",
        "run",
        "random-number-mcp"
      ]
    }
  }
}

Note: Replace <path_to_your_repo>/random-number-mcp with the absolute path to your cloned repository.

Building

# Build package
uv build

# Test installation
uv run --with dist/*.whl random-number-mcp

Release Checklist

Update Version:
- Increment the version number in pyproject.toml and src/__init__.py.
Update Changelog:
- Add a new entry in CHANGELOG.md for the release.
  - Draft notes with coding agent using git diff context.
```
Update the @CHANGELOG.md for the latest release.
List all significant changes, bug fixes, and new features.
Here's the git diff:
[GIT_DIFF]
```
- Commit along with any other pending changes.
Create GitHub Release:
- Draft a new release on the GitHub UI.
  - Tag release using UI.
- The GitHub workflow will automatically build and publish the package to PyPI.

Testing with MCP Inspector

For exploring and/or developing this server, use the MCP Inspector npm utility:

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run local development server with the inspector
npx @modelcontextprotocol/inspector uv run random-number-mcp

# Run PyPI production server with the inspector
npx @modelcontextprotocol/inspector uvx random-number-mcp

Random Number MCP