Why
LLMs can't be random.
Language models are fundamentally deterministic. When an agent needs to flip a coin, roll dice, shuffle a playlist, or pick a random name, it fakes it. Random MCP gives agents access to real randomness through simple tools.
REST API
Simple endpoints. Zero dependencies.
Hit a URL, get randomness back. Works with any language, any framework, any agent.
Numbers & Dice
curl
# Roll 2d20
curl randommcp.com/api/dice?notation=2d20
{ "rolls": [14, 7], "total": 21 }
# Random integer between 1 and 100
curl randommcp.com/api/number?min=1&max=100
{ "result": 73 }Choices & Shuffling
curl
# Pick one from a list
curl -X POST randommcp.com/api/choice \
-d '{"items": ["red", "blue", "green"]}'
{ "result": "blue" }
# Shuffle an array
curl -X POST randommcp.com/api/shuffle \
-d '{"items": [1, 2, 3, 4, 5]}'
{ "result": [3, 1, 5, 2, 4] }Generators
curl
# Random name
curl randommcp.com/api/name
{ "first": "Mara", "last": "Okonkwo" }
# Random hex color
curl randommcp.com/api/color
{ "hex": "#7c3aed", "rgb": [124, 58, 237] }UUIDs & Passwords
curl
# Generate a UUID
curl randommcp.com/api/uuid
{ "uuid": "f47ac10b-58cc-4372-a567..." }
# Random password
curl randommcp.com/api/password?length=16
{ "password": "kX9#mPq2!vR7wL4z" }MCP Server
Give your agent a pair of dice.
Install the MCP server and your agent gets randomness tools natively. Works with Claude, GPT, and any MCP-compatible client.
claude_desktop_config.json
{
"mcpServers": {
"random": {
"url": "https://randommcp.com/api/mcp"
}
}
}catalogDiscover all available generators — dice, names, colors, passwords, designer personas, and more.
randomExecute any generator by ID. Roll dice, flip coins, shuffle lists, draw cards — 17 generators in one tool.
Example usage
// Roll 2d6
random({ generator_id: "roll_dice", params: { notation: "2d6" } })
// Pick from a list
random({ generator_id: "random_choice", params: { items: ["a", "b", "c"] } })
// Generate a random name
random({ generator_id: "generate_name" })Agent Prompt
Drop this into your agent.
Paste this prompt into Claude Code, Cursor, Codex, or any MCP-compatible agent so it knows what tools are available and when to use them.
agent-prompt.md
You have access to the Random MCP server at https://randommcp.com/api/mcp.
It provides real randomness tools — use them whenever you need unpredictable results.
LLMs cannot generate true randomness on their own, so always delegate to these tools.
## Tools
### catalog
Discover available random generators. Returns IDs, descriptions, parameters, and examples.
- `query` (optional string): filter by keyword (e.g. "dice", "designer", "name")
### random
Execute a generator by ID. Pass the generator ID and its parameters.
- `generator_id` (required string): the generator to run
- `params` (optional object): parameters for the generator
## Quick Reference — Generator IDs
### Numbers & Dice
| ID | Params |
|----|--------|
| random_number | min, max, count, float, precision |
| roll_dice | notation (e.g. "2d6"), count |
| flip_coin | count |
### Selection & Ordering
| ID | Params |
|----|--------|
| random_choice | items, count, weights |
| weighted_random | items (value+weight objects), count |
| sample_list | items, count, unique |
| shuffle | items |
### Generators
| ID | Params |
|----|--------|
| generate_name | count, gender (male/female/any) |
| generate_uuid | count |
| generate_password | length, count, uppercase, lowercase, numbers, symbols |
| random_color | count, format (hex/rgb/hsl) |
| lorem_ipsum | type (words/sentences/paragraphs), count |
### Cards & Games
| ID | Params |
|----|--------|
| draw_card | count, deck (standard/tarot) |
### Designer Personas
| ID | Params | Note |
|----|--------|------|
| random_designer | seed | Returns structured traits |
| designer_bio | seed | AI-generated bio |
| designer_approach | seed | AI-generated design approach |
| designer_worldview | seed | AI-generated philosophy |
| designer_life_story | seed | AI-generated career narrative |
## Usage Examples
```
// Roll 2d6
random({ generator_id: "roll_dice", params: { notation: "2d6" } })
// Pick 3 random items from a list
random({ generator_id: "random_choice", params: { items: ["a", "b", "c", "d"], count: 3 } })
// Generate a random designer bio
random({ generator_id: "designer_bio", params: { seed: 42 } })
// Discover generators matching "color"
catalog({ query: "color" })
```
## When to use
- Whenever the task involves chance, randomness, or unpredictability — dice, coins, shuffles, picks
- When generating test/mock data — names, UUIDs, passwords, colors, lorem ipsum
- When you need a creative random persona for design exercises or brainstorming
- When the user explicitly asks for something "random"
- Do NOT guess or simulate randomness yourself — always call the tool
## Reproducibility
Designer generators accept an optional `seed` parameter (integer). Passing the same seed produces the same trait selection every time, useful for reproducible tests or demos.