Content
# 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
```bash
# 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):
```json
{
"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
```bash
# 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
