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.

> Looking for the agent skill version? random-number-skills implements the same random number generation strategy as an agent skill instead of an MCP server.

Demo Video

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

Tools

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",
        "/random-number-mcp",
        "run",
        "random-number-mcp"
      ]
    }
  }
}

Note: Replace `/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

1. Update Version:

2. Update Changelog:

Update the @CHANGELOG.md for the latest release.
        List all significant changes, bug fixes, and new features.
        Here's the git diff:
        [GIT_DIFF]

3. Create GitHub Release:

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

MCP Registry

mcp-name: io.github.zazencodes/random-number-mcp

License

MIT License - see LICENSE file for details.