MCP Rand

A Model Context Protocol (MCP) server providing various random generation utilities, including UUID, numbers, strings, passwords, Gaussian distribution, dice rolling, and card drawing.

Installation

npm install mcp-rand

Or install globally:

npm install -g mcp-rand

Features

UUID Generator

• Generates RFC 4122 version 4 UUIDs
• Uses Node's native crypto module for secure random generation
• No parameters required

Random Number Generator

• Generates random numbers within a specified range
• Configurable minimum and maximum values (inclusive)
• Defaults to range 0-100 if no parameters provided

Gaussian Random Generator

• Generates random numbers following a Gaussian (normal) distribution
• Normalized to range 0-1
• No parameters required

Random String Generator

• Generates random strings with configurable length and character sets
• Supports multiple character sets:
  • alphanumeric (default): A-Z, a-z, 0-9
  • numeric: 0-9
  • lowercase: a-z
  • uppercase: A-Z
  • special: !@#$%^&*()_+-=[]{};'"\|,.<>/?
• Configurable string length (defaults to 10)

Password Generator

• Generates strong passwords with a mix of character types
• Ensures at least one character from each type (uppercase, lowercase, numbers, special)
• Configurable length (minimum 8, default 16)
• WARNING: While passwords are generated locally, it's recommended to use a dedicated password manager

Dice Roller

• Roll multiple dice using standard dice notation
• Supports notation like "2d6" (two six-sided dice), "1d20" (one twenty-sided die)
• Returns individual rolls and total for each set of dice
• Can roll multiple different dice sets at once (e.g., "2d6", "1d20", "4d4")

Card Drawer

• Draw cards from a standard 52-card deck
• Maintains deck state between draws using base64 encoding
• Returns drawn cards and remaining deck state
• Supports drawing any number of cards up to the deck size
• Properly shuffles available cards before each draw

Usage

As a CLI Tool

npx mcp-rand

Integration with MCP Clients

Add to your MCP client configuration:

{
  "mcpServers": {
    "mcp-rand": {
      "command": "node",
      "args": ["path/to/mcp-rand/build/index.js"],
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Example Usage

// Generate UUID
const uuid = await client.callTool('generate_uuid', {});
console.log(uuid); // e.g., "550e8400-e29b-41d4-a716-446655440000"

// Generate random number
const number = await client.callTool('generate_random_number', {
  min: 1,
  max: 100
});
console.log(number); // e.g., 42

// Generate Gaussian random number
const gaussian = await client.callTool('generate_gaussian', {});
console.log(gaussian); // e.g., 0.6827

// Generate random string
const string = await client.callTool('generate_string', {
  length: 15,
  charset: 'alphanumeric'
});
console.log(string); // e.g., "aB9cD8eF7gH6iJ5"

// Generate password
const password = await client.callTool('generate_password', {
  length: 20
});
console.log(password); // e.g., "aB9#cD8$eF7@gH6*iJ5"

// Roll dice
const rolls = await client.callTool('roll_dice', {
  dice: ['2d6', '1d20', '4d4']
});
console.log(rolls);
/* Output example:
[
  {
    "dice": "2d6",
    "rolls": [3, 1],
    "total": 4
  },
  {
    "dice": "1d20",
    "rolls": [4],
    "total": 4
  },
  {
    "dice": "4d4",
    "rolls": [2, 3, 2, 3],
    "total": 10
  }
]
*/

// Draw cards
const draw1 = await client.callTool('draw_cards', {
  count: 5
});
console.log(draw1);
/* Output example:
{
  "drawnCards": [
    { "suit": "hearts", "value": "A" },
    { "suit": "diamonds", "value": "7" },
    { "suit": "clubs", "value": "K" },
    { "suit": "spades", "value": "2" },
    { "suit": "hearts", "value": "10" }
  ],
  "remainingCount": 47,
  "deckState": "t//+///bDw=="
}
*/

// Draw more cards using previous deck state
const draw2 = await client.callTool('draw_cards', {
  count: 3,
  deckState: draw1.deckState
});
console.log(draw2);
/* Output example:
{
  "drawnCards": [
    { "suit": "diamonds", "value": "Q" },
    { "suit": "clubs", "value": "5" },
    { "suit": "spades", "value": "J" }
  ],
  "remainingCount": 44,
  "deckState": "l//+//zbDw=="
}
*/

Contributing

Please see CONTRIBUTING.md for development setup and guidelines.

License

ISC