README.md•6.82 kB
# 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
```bash
# Install globally
npm install -g random-org-mcp-server
# Verify installation
random-org-mcp --version
```
#### Method 2: Use without Installation
```bash
# Run directly with npx (no installation required)
npx random-org-mcp-server
```
#### Method 3: Local Project Installation
```bash
# 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:
```bash
git clone https://github.com/QianJue-CN/TRUERandomMCP.git
cd TRUERandomMCP
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## Configuration
### 🔑 Get API Key
1. Visit [api.random.org](https://api.random.org/api-keys/beta) 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:
```bash
# Copy example file (if building from source)
cp .env.example .env
```
Edit `.env` file:
```env
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):
```json
{
"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:
```json
{
"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
```json
{
"mcpServers": {
"random-org": {
"command": "random-org-mcp",
"env": {
"RANDOM_ORG_API_KEY": "your_api_key_here"
}
}
}
}
```
#### Using Local Installation
```json
{
"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:
```bash
random-org-mcp
```
#### Using npx (no installation required):
```bash
npx random-org-mcp-server
```
#### From source:
```bash
npm start
```
### 🛠️ Development
For development with auto-reload:
```bash
npm run dev
```
### Tool Examples
#### Generate Random Integers
```json
{
"name": "generateIntegers",
"arguments": {
"n": 5,
"min": 1,
"max": 100,
"replacement": true,
"base": 10
}
}
```
#### Generate Random Strings
```json
{
"name": "generateStrings",
"arguments": {
"n": 3,
"length": 8,
"characters": "abcdefghijklmnopqrstuvwxyz0123456789",
"replacement": true
}
}
```
#### Generate UUIDs
```json
{
"name": "generateUUIDs",
"arguments": {
"n": 5
}
}
```
#### Generate Gaussian Numbers
```json
{
"name": "generateGaussians",
"arguments": {
"n": 10,
"mean": 0,
"standardDeviation": 1,
"significantDigits": 6
}
}
```
#### Get Usage Statistics
```json
{
"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](https://github.com/QianJue-CN/TRUERandomMCP/issues).
For api.random.org API issues, please refer to their [documentation](https://api.random.org/json-rpc/4).