Random Number

What is random-number-mcp?

random-number-mcp is a production-ready server that provides Large Language Models (LLMs) with robust random number generation capabilities. It leverages Python's standard library, offering both pseudorandom and cryptographically secure operations for various data types and tasks.

How to use random-number-mcp?

To use random-number-mcp, you need to configure it within your Claude Desktop environment or integrate it as an MCP server. For Claude Desktop, add the provided JSON configuration to your claude_desktop_config.json file. For development or testing, you can use uv to install dependencies and run the server locally. The project also provides examples of how to call each random generation tool with specific arguments.

Key Features of random-number-mcp

• Comprehensive Random Generation: Offers tools for generating random integers (random_int), floats (random_float), weighted choices (random_choices), list shuffling (random_shuffle), and unique item sampling (random_sample).
• Cryptographically Secure Options: Includes secure_token_hex for generating secure hexadecimal tokens and secure_random_int for cryptographically secure integers, utilizing Python's secrets module.
• Python Standard Library Based: Built entirely on Python's standard library, ensuring reliability and minimizing external dependencies.
• MCP Server: Designed as an MCP (Model Context Protocol) server, enabling seamless integration with LLMs and other AI applications.
• Clear Tool Reference: Provides detailed documentation for each tool, including parameters and examples.

Use Cases of random-number-mcp

• LLM Applications: Empowering LLMs with the ability to generate diverse random data for various tasks, such as creating dynamic content, simulating scenarios, or generating unique identifiers.
• Gaming and Simulations: Generating random numbers for game mechanics, simulations, and statistical modeling.
• Security and Cryptography: Creating secure tokens, keys, and other cryptographic elements using the cryptographically secure functions.
• Data Science and Analytics: Sampling data, shuffling datasets, and performing random selections for experiments and analysis.
• Development and Testing: Generating test data and simulating random events for application development and testing.

FAQ from random-number-mcp

Q: What is the difference between standard and secure functions? A: Standard functions (random_int, random_float, random_choices, random_shuffle) use Python's random module, which is fast but not cryptographically secure, suitable for simulations and games. Secure functions (secure_token_hex, secure_random_int) use Python's secrets module, which is slower but cryptographically secure, suitable for tokens and keys.

Q: How do I set up random-number-mcp with Claude Desktop? A: You need to add a specific JSON configuration to your claude_desktop_config.json file, typically located in ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Claude/claude_desktop_config.json on Windows.

Q: What are the prerequisites for developing random-number-mcp? A: You need Python 3.10+ and the uv package manager. The development section in the README provides detailed setup instructions, including how to install dependencies, run tests, and perform linting and type checking.

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

1. Update Version:

   • Increment the version number in pyproject.toml and src/__init__.py.

2. 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.

3. 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

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📚 Links

• Model Context Protocol
• FastMCP Documentation
• Python random module
• Python secrets module