Random.org MCP Server

A Model Context Protocol (MCP) server that provides access to the api.random.org service for generating true random numbers, strings, UUIDs, and more.

Features

This MCP server provides the following tools:

• generateIntegers - Generate true random integers within a specified range
• generateIntegerSequences - Generate sequences of true random integers
• generateDecimalFractions - Generate random decimal fractions between 0 and 1
• generateGaussians - Generate random numbers from a Gaussian distribution
• generateStrings - Generate random strings from specified characters
• generateUUIDs - Generate true random UUIDs (version 4)
• generateBlobs - Generate random binary data in base64 or hex format
• getUsage - Get API usage statistics

Installation & Deployment

🚀 Quick Start with npm (Recommended)

Method 1: Global Installation

# Install globally
npm install -g random-org-mcp-server

# Verify installation
random-org-mcp --version

Method 2: Use without Installation

# Run directly with npx (no installation required)
npx random-org-mcp-server

Method 3: Local Project Installation

# Install in your project
npm install random-org-mcp-server

# Run from node_modules
npx random-org-mcp-server

🛠️ Build from Source

1. Clone this repository:

git clone https://github.com/QianJue-CN/TRUERandomMCP.git
cd TRUERandomMCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

🔑 Get API Key

1. Visit api.random.org to get a free API key
2. Register and obtain your API key

⚙️ Configuration Methods

Method 1: Environment Variables (Recommended)

Create a .env file in your working directory:

# Copy example file (if building from source)
cp .env.example .env

Edit .env file:

RANDOM_ORG_API_KEY=your_api_key_here
RATE_LIMIT_REQUESTS_PER_SECOND=1
RATE_LIMIT_BURST_SIZE=5
REQUEST_TIMEOUT_MS=10000
MAX_RETRIES=3
RETRY_DELAY_MS=1000

Method 2: MCP Client Configuration

Configure directly in your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "random-org": {
      "command": "npx",
      "args": ["random-org-mcp-server"],
      "env": {
        "RANDOM_ORG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Environment Variables

• RANDOM_ORG_API_KEY (required) - Your api.random.org API key
• RATE_LIMIT_REQUESTS_PER_SECOND (optional, default: 1) - Rate limiting
• RATE_LIMIT_BURST_SIZE (optional, default: 5) - Burst size for rate limiting
• REQUEST_TIMEOUT_MS (optional, default: 10000) - Request timeout in milliseconds
• MAX_RETRIES (optional, default: 3) - Maximum number of retries
• RETRY_DELAY_MS (optional, default: 1000) - Delay between retries

Usage

🔗 MCP Client Integration

Claude Desktop Configuration

1. Locate your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the Random.org MCP server configuration:

{
  "mcpServers": {
    "random-org": {
      "command": "npx",
      "args": ["random-org-mcp-server"],
      "env": {
        "RANDOM_ORG_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Restart Claude Desktop

Alternative Configurations

Using Global Installation

{
  "mcpServers": {
    "random-org": {
      "command": "random-org-mcp",
      "env": {
        "RANDOM_ORG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "random-org": {
      "command": "node",
      "args": ["node_modules/random-org-mcp-server/dist/index.js"],
      "env": {
        "RANDOM_ORG_API_KEY": "your_api_key_here"
      }
    }
  }
}

Running the Server

🚀 Production Usage

If installed globally:

random-org-mcp

Using npx (no installation required):

npx random-org-mcp-server

From source:

npm start

🛠️ Development

For development with auto-reload:

npm run dev

Tool Examples

Generate Random Integers

{
  "name": "generateIntegers",
  "arguments": {
    "n": 5,
    "min": 1,
    "max": 100,
    "replacement": true,
    "base": 10
  }
}

Generate Random Strings

{
  "name": "generateStrings",
  "arguments": {
    "n": 3,
    "length": 8,
    "characters": "abcdefghijklmnopqrstuvwxyz0123456789",
    "replacement": true
  }
}

Generate UUIDs

{
  "name": "generateUUIDs",
  "arguments": {
    "n": 5
  }
}

Generate Gaussian Numbers

{
  "name": "generateGaussians",
  "arguments": {
    "n": 10,
    "mean": 0,
    "standardDeviation": 1,
    "significantDigits": 6
  }
}

Get Usage Statistics

{
  "name": "getUsage",
  "arguments": {}
}

API Limits

The api.random.org service has the following limits:

• Integers: 1-10,000 numbers per request
• Integer Sequences: 1-10,000 sequences, each 1-10,000 numbers long
• Decimal Fractions: 1-10,000 numbers per request
• Gaussians: 1-10,000 numbers per request
• Strings: 1-10,000 strings per request, each 1-20 characters long
• UUIDs: 1-1,000 UUIDs per request
• Blobs: 1-100 blobs per request, each 1-1,048,576 bytes

Error Handling

The server includes comprehensive error handling:

• Input validation for all parameters
• Rate limiting to respect API limits
• Automatic retries with exponential backoff
• Detailed error messages for troubleshooting

Development

Scripts

• npm run build - Build the TypeScript code
• npm start - Run the compiled server
• npm run dev - Run in development mode with auto-reload
• npm run clean - Clean the build directory

Project Structure

src/
├── index.ts           # Main entry point
├── server.ts          # MCP server implementation
├── randomOrgClient.ts # API client for random.org
├── rateLimiter.ts     # Rate limiting implementation
├── config.ts          # Configuration management
└── types.ts           # TypeScript type definitions

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues related to this MCP server, please open an issue on GitHub. For api.random.org API issues, please refer to their documentation.