Randomuser

🚀 RandomUser MCP Server

A MCP server that offers enhanced features, supports random user generation, and integrates the randomuser.me API. This server adds functionalities such as custom formatting, password generation, and nationality assignment by weight.

🚀 Quick Start

📦 Installation

1. Clone the repository:

   git clone https://github.com/rycid/randomuserMCP.git
   cd randomuserMCP
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

💻 Usage Examples

Basic Usage

Add the following content to your MCP configuration file (claude_desktop_config.json or cline_mcp_settings.json):

{
  "mcpServers": {
    "randomuser": {
      "command": "node",
      "args": ["path/to/randomuserMCP/build/index.js"]
    }
  }
}

Available Tools

Get a Single Random User (get_random_user)

Retrieve information about a single random user by configuring parameters.

{
  "gender": "female",
  "nationality": "US",
  "fields": {
    "mode": "include", // or "exclude"
    "values": ["name", "email", "phone"]
  },
  "format": {
    "type": "json",
    "structure": {
      "flattenObjects": true,
      "nameFormat": "full" // Optional: full, first_last, separate
    }
  },
  "password": {
    "charsets": ["special", "upper", "lower", "number"],
    "minLength": 8,
    "maxLength": 12
  }
}

Get Multiple Random Users (get_multiple_users)

Obtain a specified number of random users with nationality distribution assigned by weight.

{
  "count": 10,
  "nationality": ["US", "GB", "FR"],
  "nationalityWeights": {
    "US": 0.5,
    "GB": 0.3,
    "FR": 0.2
  },
  "fields": {
    "mode": "include",
    "values": ["name", "email", "nat"]
  },
  "format": {
    "type": "csv",
    "csv": {
      "delimiter": ",",
      "includeHeader": true
    }
  }
}

Supported Output Formats

The server supports multiple output formats:

JSON (Default)

• Optional nested or flat object structure
• Customizable name formats (full, first_last, separate)
• Multiple date format options (iso, unix, formatted)

CSV

• Customizable delimiter
• Option to include headers
• Automatic flattening of data structures

SQL

• Supports multiple database dialects (MySQL, PostgreSQL, SQLite)
• Optional generation of CREATE TABLE statements
• Data escaping and type handling

XML

• Standard XML format output
• Supports nested data structures
• Properly escapes special characters

Field Selection

Include or exclude specific fields as needed:

{
  "fields": {
    "mode": "include", // or "exclude"
    "values": [
      "name",
      "phone",
      "email",
      "location",
      "picture",
      "dob",
      "login",
      "registered",
      "id",
      "cell",
      "nat"
    ]
  }
}

Supported Countries List

• AU: Australia
• BR: Brazil
• CA: Canada
• CH: Switzerland
• DE: Germany
• DK: Denmark
• ES: Spain
• FI: Finland
• FR: France
• GB: United Kingdom
• IE: Ireland
• IN: India
• IR: Iran
• MX: Mexico
• NL: Netherlands
• NO: Norway
• NZ: New Zealand
• SE: Sweden

🔧 Technical Details

Clone the Repository

git clone https://github.com/rycid/randomuserMCP.git
cd randomuserMCP

Install Dependencies

npm install

Build the Project

npm run build

🤝 Contribution Guidelines

Contributions are welcome! Please refer to the Contribution Guidelines to learn how to get involved.

📄 License

This project is licensed under the MIT License. See LICENSE for more details.

📞 Contact

If you need to contact us, please send an email to: contact@rycid.com