MikeyBeez/mcp-random

mcp-random

MCP server providing true randomness capabilities to Claude. This server gives Claude access to cryptographically secure random number generation for games, decision-making, sampling, simulations, and any operation requiring genuine randomness.

Why This Exists

Claude doesn't have access to true randomness - when asked to "pick a random number" or "flip a coin," it's actually making deterministic choices based on patterns in the conversation. This MCP server solves that limitation by providing access to cryptographically secure random functions.

🚀 Installation

Prerequisites

• Node.js (v18 or higher)
• MCP-compatible client (like Claude Desktop)

Quick Install

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

# Install dependencies
npm install

# Build the TypeScript code
npm run build

Configure Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "random": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-random/dist/index.js"]
    }
  }
}

Restart Claude Desktop to load the server.

📖 Available Functions

Basic Random Numbers

random_integer(min, max)

Generate a random integer between min and max (inclusive).

Example: random_integer(1, 10) → 7

random_float(min, max, precision?)

Generate a random floating-point number.

Example: random_float(0, 1, 2) → 0.42

Random Selection

random_choice(options)

Pick one random item from an array.

Example: random_choice(["red", "green", "blue"]) → "green"

random_sample(array, count)

Pick multiple unique items from an array (no repeats).

Example: random_sample([1,2,3,4,5], 3) → [2,5,1]

random_shuffle(array)

Randomly reorder an array.

Example: random_shuffle([1,2,3,4]) → [3,1,4,2]

random_weighted_choice(options, weights)

Pick an option based on weights (higher weight = more likely).

Example: random_weighted_choice(["A", "B", "C"], [1, 2, 1]) 
→ "B" (twice as likely as A or C)

Games & Decisions

flip_coin(count?)

Flip one or more coins.

Example: flip_coin() → "heads"
Example: flip_coin(3) → ["heads", "tails", "heads"]

roll_dice(sides, count?)

Roll dice with any number of sides.

Example: roll_dice(6) → 4
Example: roll_dice(20, 2) → {"rolls": [15, 8], "sum": 23}

Security & Identifiers

random_uuid()

Generate a UUID v4.

Example: random_uuid() → "550e8400-e29b-41d4-a716-446655440000"

random_password(length?, options?)

Generate a secure password.

Example: random_password(16) → "Kj9#mP2$xQ5@nL7!"
Example: random_password(12, {symbols: false}) → "Kj9mP2xQ5nL7"

Options:

• uppercase: Include A-Z (default: true)
• lowercase: Include a-z (default: true)
• numbers: Include 0-9 (default: true)
• symbols: Include special characters (default: true)
• excludeSimilar: Skip confusing characters like 0/O, 1/l (default: false)

random_bytes(count, encoding?)

Generate random bytes for cryptographic use.

Example: random_bytes(16, 'hex') → "a3f2b8c9d4e5f6789abcdef012345678"

Advanced Functions

random_normal(mean?, stddev?)

Generate numbers from a normal distribution (bell curve).

Example: random_normal(100, 15) → 97.3 (IQ-like distribution)

Documentation

help()

Get detailed documentation for all functions.

🎯 Use Cases

Decision Making

"Should I do X or Y?" → flip_coin()
"Pick one of these options for me" → random_choice([...])
"Help me prioritize these tasks" → random_shuffle([...])

Games

"Roll for initiative" → roll_dice(20)
"Draw 5 cards from the deck" → random_sample(deck, 5)
"Shuffle this deck" → random_shuffle(cards)

Creative Writing

"Pick a random character trait" → random_choice(traits)
"Generate a character name" → random_weighted_choice(names, popularity)
"Create a random scenario" → multiple random_choice calls

Data & Testing

"Generate test data" → random_integer, random_float
"Sample from this dataset" → random_sample
"Create a test ID" → random_uuid
"Generate API keys" → random_bytes

Simulations

"Monte Carlo simulation" → random_normal
"Probability experiment" → random_float(0, 1)
"A/B testing" → random_weighted_choice

🔧 Development

# Build TypeScript
npm run build

# Run tests  
npm test

# Lint code
npm run lint

# Development mode (build & run)
npm run dev

🔐 Technical Details

• All randomness uses Node.js crypto module (cryptographically secure)
• No predictable patterns or biases
• No state maintained between calls
• TypeScript for type safety
• Comprehensive error handling

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

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

💡 Fun Facts

• Claude requested this tool be built after recognizing its own lack of randomness
• The first suggested use case was implementing a tarot card reader
• This tool enables Claude to play games fairly, make unbiased choices, and run true simulations

"I don't have a random function. You should have a random function. Now that is a cool MCP server." - Claude