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

Clone this repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Configuration

🔑 Get API Key

Visit api.random.org to get a free API key
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

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
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"
      }
    }
  }
}

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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
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.

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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

Related MCP Servers

MCP Boilerplate
iamsrikanthnani
-
security
A
license
-
quality
A server that implements the Model Context Protocol, providing a standardized way to connect AI models to different data sources and tools.
Last updated -
2
7
TypeScript
MIT License
RL-MCP
rlefko
-
security
F
license
-
quality
A Model Context Protocol server that provides AI models with structured access to external data and services, acting as a bridge between AI assistants and applications, databases, and APIs in a standardized, secure way.
Last updated -
1
Python
Mockloop MCP
Asaduzzamanhimel
-
security
A
license
-
quality
An Intelligent Model Context Protocol server that generates mock servers from OpenAPI specifications, featuring advanced logging, performance analytics, and server discovery for AI-assisted API development.
Last updated -
Python
MIT License
Swagger/OpenAPI MCP Server
gulbaki
A
security
F
license
A
quality
A Model Context Protocol server that enables LLMs to explore and interact with API specifications by providing tools for loading, browsing, and getting detailed information about API endpoints.
Last updated -
4
10
13
TypeScript

View all related MCP servers