Skip to main content
Glama
random-web3-mcp
by suxiongye

RandomWeb3MCP - Web3 Random Element Generation Service

RandomWeb3MCP is a random element generation service based on EVM block hash. The service provides various random element generation tools that can be used in games, finance, testing, and other fields.

Features

  • Verifiability: All random numbers are generated based on blockchain hash, ensuring fairness and verifiability

  • Diversity: Supports various random number generation scenarios, from basic random numbers to complex probability distributions

  • Reliability: Uses blockchain as entropy source to ensure randomness quality

  • Usability: Provides simple and intuitive API interfaces for easy integration

Related MCP server: Random Value MCP Server

Installation

git clone git@github.com:suxiongye/random-web3-mcp.git
pip install -e .

Quick Start

Configuration in tico or Cursor

Add random-web3-mcp service configuration in Cursor settings:

{
  "mcpServers": {
    "random-web3-mcp": {
      "command": "uv",
      "args": ["--directory", "local_repo_directory/zxl-mcp-server", "run", "main.py"]
    }
  }
}

Tool List

generate_basic_random

Name

Basic Random Number Generator

Function

Generate a random integer within the specified range

Parameters

  • min_value (int, optional): Minimum value (inclusive). Defaults to 0.

  • max_value (int, optional): Maximum value (inclusive). Defaults to 1000000.

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing the random number result

Application Scenarios

  1. Lottery systems

  2. Game random numbers

  3. Random ID generation

  4. Test data generation

generate_random_array

Name

Random Array Generator

Function

Generate a random array of specified length

Parameters

  • array_length (int, optional): Array length. Defaults to 1.

  • min_value (int, optional): Minimum value. Defaults to 0.

  • max_value (int, optional): Maximum value. Defaults to 1000000.

  • salt (str, optional): Random number salt value. Defaults to ''

Returns

JSON string containing the random array

Application Scenarios

  1. Batch random number generation

  2. Random sampling

  3. Test dataset generation

  4. Random task assignment

generate_random_weighted

Name

Weighted Random Selector

Function

Randomly select an option based on weights

Parameters

  • options (List[str]): List of options

  • weights (List[int]): Corresponding weight list (0-1000)

  • salt (str, optional): Random number salt value. Defaults to ''

Returns

JSON string containing the selection result

Application Scenarios

  1. Lottery systems (prizes with different probabilities)

  2. Random drops (weighted item drops)

  3. Task assignment (based on priority)

  4. A/B testing (experiment groups with different ratios)

generate_random_feature

Name

Random Feature Allocator

Function

Generate a set of random feature values for objects, each feature value within its specified range. Feature values are encoded into a bitmap, with each feature occupying 8 bits

Parameters

  • feature_count (int): Number of features to generate

  • feature_max_values (List[int]): List of maximum values for each feature, length must equal feature_count

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing feature values and bitmap, formatted as:

{
    "requestId": "Generated request ID",
    "features": [List of feature values],
    "featureBitmap": Feature bitmap value
}

Application Scenarios

  1. Game character attribute generation (strength, agility, intelligence, etc.)

  2. Equipment attribute randomization (attack, defense, speed, etc.)

  3. Biological trait simulation (genes, traits, etc.)

  4. Random scene generation (terrain, weather, environment, etc.)

generate_distribution

Name

Probability Distribution Random Generator

Function

Generate random numbers according to specified probability distribution type and parameters. Supports various common probability distributions.

Parameters

  • distribution_type (int): Distribution type:

    • 1 = Uniform distribution (parameters: [min_value, max_value])

    • 2 = Normal distribution (parameters: [mean, standard_deviation])

    • 3 = Exponential distribution (parameters: [scale_parameter])

    • 4 = Binomial distribution (parameters: [trials, success_probability])

  • distribution_parameters (List[float]): Distribution parameter list

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing random value and distribution information, formatted as:

{
    "requestId": "Generated request ID",
    "randomValue": Generated random value,
    "distributionMetadata": {
        "distributionType": Distribution type,
        ...Distribution parameters
    }
}

Application Scenarios

  1. Financial market simulation (return distribution, risk analysis)

  2. Natural phenomena simulation (particle distribution, noise generation)

  3. Load testing (user behavior distribution)

  4. Statistical sampling (experimental data generation)

generate_random_event

Name

Random Event Trigger

Function

Trigger a series of events based on given probabilities, each event has an independent trigger probability. Uses bitmap to record trigger status for easy processing.

Parameters

  • event_count (int): Total number of events

  • event_probabilities (List[int]): Trigger probability for each event (0-1000, representing 0-100%)

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing event trigger results, formatted as:

{
    "requestId": "Generated request ID",
    "triggeredEvents": Event trigger bitmap,
    "eventResults": [
        {
            "eventId": Event ID,
            "probability": Trigger probability,
            "triggered": Whether triggered,
            "randomValue": Random value
        },
        ...
    ]
}

Application Scenarios

  1. Game random events (trigger plot, drop items)

  2. Probability effect determination (skill trigger, combo determination)

  3. Risk event simulation (fault prediction, accident events)

  4. Multiple condition determination (combined probability events)

generate_random_seed

Name

Random Seed Generator

Function

Generate high-entropy random seed for encryption or other scenarios requiring high-quality random numbers. Uses blockchain hash as entropy source to ensure randomness.

Parameters

  • seed_length (int): Length of seed to generate (in bytes)

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing random seed, formatted as:

{
    "requestId": "Generated request ID",
    "randomSeed": "Random seed in hexadecimal format",
    "entropy": Estimated entropy value
}

Application Scenarios

  1. Key generation (encryption keys, signature seeds)

  2. Security tokens (session identifiers, authentication tokens)

  3. Random number initialization (PRNG seeds, simulation initial states)

  4. Unique identifier generation (UUID seeds, random identifiers)

shuffle_array

Name

Random Array Shuffler

Function

Randomly shuffle the input array, ensuring each element has an equal probability of appearing in any position. Uses Fisher-Yates shuffle algorithm to ensure fairness.

Parameters

  • input_array (List): Array to be shuffled, elements can be of any type

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing the shuffled array, formatted as:

{
    "requestId": "Generated request ID",
    "shuffledArray": [Shuffled array]
}

Application Scenarios

  1. Game shuffling (playing cards, mahjong tiles)

  2. Random ordering (question order, playlist)

  3. Random grouping (team assignment, experiment grouping)

  4. Data shuffling (training dataset, test cases)

generate_coordinate

Name

Random Coordinate Generator

Function

Generate random coordinate points in a specified dimensional space, each dimension has its own value range. Supports coordinate generation in any number of dimensions.

Parameters

  • dimensions (int): Number of coordinate dimensions (1D, 2D, 3D, etc.)

  • min_values (List[float]): List of minimum values for each dimension

  • max_values (List[float]): List of maximum values for each dimension

  • coordinate_count (int): Number of coordinate points to generate

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing random coordinates, formatted as:

{
    "requestId": "Generated request ID",
    "coordinates": [
        [x1, y1, z1, ...],  # First point coordinates
        [x2, y2, z2, ...],  # Second point coordinates
        ...
    ]
}

Application Scenarios

  1. Game object positioning (NPC locations, item distribution)

  2. Particle systems (effect generation, particle distribution)

  3. Map generation (terrain height, resource distribution)

  4. Spatial sampling (3D modeling, spatial analysis)

generate_rarity

Name

Rarity Random Allocator

Function

Generate random coordinate points in a specified dimensional space, each dimension has its own value range. Supports coordinate generation in any number of dimensions.

Parameters

  • item_count: Project quantity

  • rarity_tiers: Rarity level array

  • rarity_percentages: Probability percentage for each rarity level

  • guaranteed_minimums: Guaranteed quantity for each rarity level (optional)

  • salt (str, optional): Random number salt value for increased randomness. Defaults to ''

Returns

JSON string containing random rarity array, formatted as:

{
    "requestId": "Generated request ID",
    "rarityDistribution": [Rarity allocation result]
}

Application Scenarios

  1. Game item drops (different rarity equipment, items)

  2. Lottery systems (prizes with different probabilities)

  3. Resource allocation (different rarity resources, materials)

  4. Random event trigger (different probability events)

Application Scenarios

Game Development

  • Random item drops

  • Character attribute generation

  • Map random generation

  • Probability event trigger

Financial Application

  • Risk simulation

  • Investment portfolio analysis

  • Market behavior simulation

Test Data

  • Random test case generation

  • Load test data

  • Performance test sample

Scientific Calculation

  • Monte Carlo simulation

  • Particle system simulation

  • Random sampling

Notes

  1. All random number generation depends on the blockchain hash of the Trust Chain, please ensure normal network connection

  2. Weighted random selector weight value range is 0-1000, representing 0-100% probability

  3. Probability distribution parameters need to provide correct parameter list according to specific distribution type

  4. It is recommended to use salt parameter in production environment to increase randomness

Error Handling

Service may return error types:

{
    "error": "Error message",
    "code": "Error code",
    "requestId": "Request ID"
}

Common error codes:

  • INVALID_PARAMS: Parameter error

  • NETWORK_ERROR: Network connection error

  • CHAIN_ERROR: Blockchain access error

  • INTERNAL_ERROR: Internal service error

Performance Consideration

  • Each random number generation request needs to access the blockchain, which may have a certain delay

  • It is recommended to cache frequently used random numbers

  • Pay attention to request frequency when handling a large number of concurrent requests

Contribution Guide

Welcome to submit Issue and Pull Request to help improve this project. Before submitting, please ensure:

  1. Code conforms to PEP 8 specification

  2. Appropriate test cases are added

  3. Related documents are updated

License

This project uses MIT License. See LICENSE file for details.

Available Tools

10 tools
generate_basic_randomA

Basic Random Number Generator

Generate a random integer within the specified range

Args:
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".
    min_value (int, optional): Minimum value (inclusive). Defaults to 0.
    max_value (int, optional): Maximum value (inclusive). Defaults to 1000000.

Returns:
    str: JSON string containing the random number result

Application Scenarios:
1. Lottery systems
2. Game random numbers
3. Random ID generation
4. Test data generation

Inputs: max_value, min_value, salt.

generate_coordinateA

Random Coordinate Generator

Generate random coordinate points in a specified dimensional space, each dimension has its own value range.
Supports coordinate generation in any number of dimensions.

Args:
    dimensions (int): Number of coordinate dimensions (1D, 2D, 3D, etc.)
    min_values (List[float]): List of minimum values for each dimension
    max_values (List[float]): List of maximum values for each dimension
    coordinate_count (int): Number of coordinate points to generate
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing random coordinates, formatted as:
    {
        "requestId": "Generated request ID",
        "coordinates": [
            [x1, y1, z1, ...],  # First point coordinates
            [x2, y2, z2, ...],  # Second point coordinates
            ...
        ]
    }

Application Scenarios:
1. Game object positioning (NPC locations, item distribution)
2. Particle systems (effect generation, particle distribution)
3. Map generation (terrain height, resource distribution)
4. Spatial sampling (3D modeling, spatial analysis)

Inputs: coordinate_count (required), dimensions (required), max_values (required), min_values (required), +1 more.

generate_distributionA

Probability Distribution Random Generator

Generate random numbers according to specified probability distribution type and parameters.
Supports various common probability distributions.

Args:
    distribution_type (int): Distribution type:
        1 = Uniform distribution (parameters: [min_value, max_value])
        2 = Normal distribution (parameters: [mean, standard_deviation])
        3 = Exponential distribution (parameters: [scale_parameter])
        4 = Binomial distribution (parameters: [trials, success_probability])
    distribution_parameters (List[float]): Distribution parameter list
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing random value and distribution information, formatted as:
    {
        "requestId": "Generated request ID",
        "randomValue": Generated random value,
        "distributionMetadata": {
            "distributionType": Distribution type,
            ...Distribution parameters
        }
    }

Application Scenarios:
1. Financial market simulation (return distribution, risk analysis)
2. Natural phenomena simulation (particle distribution, noise generation)
3. Load testing (user behavior distribution)
4. Statistical sampling (experimental data generation)

Inputs: distribution_parameters (required), distribution_type (required), salt.

generate_random_arrayA

Random Array Generator

Generate a random array of specified length

Args:
    salt (str, optional): Random number salt value. Defaults to "".
    array_length (int, optional): Array length. Defaults to 1.
    min_value (int, optional): Minimum value. Defaults to 0.
    max_value (int, optional): Maximum value. Defaults to 1000000.
    allow_duplicates (bool, optional): Allow duplicate values. Defaults to True.

Returns:
    str: JSON string containing the random array

Application Scenarios:
1. Batch random number generation
2. Random sampling
3. Test dataset generation
4. Random task assignment

Inputs: allow_duplicates, array_length, max_value, min_value, +1 more.

generate_random_eventA

Random Event Trigger

Trigger a series of events based on given probabilities, each event has an independent trigger probability.
Uses bitmap to record trigger status for easy processing.

Args:
    event_count (int): Total number of events
    event_probabilities (List[int]): Trigger probability for each event (0-1000, representing 0-100%)
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing event trigger results, formatted as:
    {
        "requestId": "Generated request ID",
        "triggeredEvents": Event trigger bitmap,
        "eventResults": [
            {
                "eventId": Event ID,
                "probability": Trigger probability,
                "triggered": Whether triggered,
                "randomValue": Random value
            },
            ...
        ]
    }

Application Scenarios:
1. Game random events (trigger plot, drop items)
2. Probability effect determination (skill trigger, combo determination)
3. Risk event simulation (fault prediction, accident events)
4. Multiple condition determination (combined probability events)

Inputs: event_count (required), event_probabilities (required), salt.

generate_random_featureA

Random Feature Allocator

Generate a set of random feature values for objects, each feature value within its specified range.
Feature values are encoded into a bitmap, with each feature occupying 8 bits.

Args:
    feature_count (int): Number of features to generate
    feature_max_values (List[int]): List of maximum values for each feature, length must equal feature_count
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing feature values and bitmap, formatted as:
    {
        "requestId": "Generated request ID",
        "features": [List of feature values],
        "featureBitmap": Feature bitmap value
    }

Application Scenarios:
1. Game character attribute generation (strength, agility, intelligence, etc.)
2. Equipment attribute randomization (attack, defense, speed, etc.)
3. Biological trait simulation (genes, traits, etc.)
4. Random scene generation (terrain, weather, environment, etc.)

Inputs: feature_count (required), feature_max_values (required), salt.

generate_random_seedA

Random Seed Generator

Generate high-entropy random seed for encryption or other scenarios requiring high-quality random numbers.
Uses blockchain hash as entropy source to ensure randomness.

Args:
    seed_length (int): Length of seed to generate (in bytes)
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing random seed, formatted as:
    {
        "requestId": "Generated request ID",
        "randomSeed": "Random seed in hexadecimal format",
        "entropy": Estimated entropy value
    }

Application Scenarios:
1. Key generation (encryption keys, signature seeds)
2. Security tokens (session identifiers, authentication tokens)
3. Random number initialization (PRNG seeds, simulation initial states)
4. Unique identifier generation (UUID seeds, random identifiers)

Inputs: seed_length (required), salt.

generate_random_weightedA

Weighted Random Selector

Randomly select an option based on weights

Args:
    options (List[str]): List of options
    weights (List[int]): Corresponding weight list (0-1000)
    salt (str, optional): Random number salt value. Defaults to "".

Returns:
    str: JSON string containing the selection result

Application Scenarios:
1. Lottery systems (prizes with different probabilities)
2. Random drops (weighted item drops)
3. Task assignment (based on priority)
4. A/B testing (experiment groups with different ratios)

Inputs: options (required), weights (required), salt.

generate_rarityC

Rarity Distributor Args: item_count: Number of items rarity_tiers: Array of rarity tiers rarity_percentages: Probability percentage for each rarity tier guaranteed_minimums: Minimum guaranteed count for each rarity tier (optional) salt: Additional entropy source

Inputs: item_count (required), rarity_percentages (required), rarity_tiers (required), guaranteed_minimums, +1 more.

shuffle_arrayA

Random Array Shuffler

Randomly shuffle the input array, ensuring each element has an equal probability of appearing in any position.
Uses Fisher-Yates shuffle algorithm to ensure fairness.

Args:
    input_array (List): Array to be shuffled, elements can be of any type
    salt (str, optional): Random number salt value for increased randomness. Defaults to "".

Returns:
    str: JSON string containing the shuffled array, formatted as:
    {
        "requestId": "Generated request ID",
        "shuffledArray": [Shuffled array]
    }

Application Scenarios:
1. Game shuffling (playing cards, mahjong tiles)
2. Random ordering (question order, playlist)
3. Random grouping (team assignment, experiment grouping)
4. Data shuffling (training dataset, test cases)

Inputs: input_array (required), salt.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation3/5

    The tools have overlapping purposes in random generation, with multiple tools generating random numbers or arrays (e.g., generate_basic_random, generate_random_array, generate_distribution). However, descriptions clarify distinctions like coordinate generation, distribution types, or weighted selection, helping agents differentiate between them. Some ambiguity remains, such as between generate_random_array and shuffle_array for array manipulation.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with a clear 'generate_' or 'shuffle_' prefix, making them predictable and readable. The naming convention is uniform across all tools, with no mixing of styles or deviations, which aids in easy identification and usage.

    Tool Count4/5

    With 10 tools, the count is reasonable for a random generation server, covering various aspects like basic numbers, coordinates, distributions, and shuffling. It's slightly heavy but well-scoped, as each tool addresses a specific niche in random generation without being excessive for the domain.

    Completeness4/5

    The toolset covers a broad range of random generation scenarios, including numbers, arrays, distributions, events, and seeds, with no obvious gaps for core functionalities. Minor gaps might include lack of tools for random string generation or more advanced statistical distributions, but the existing set supports most common use cases effectively.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Production-ready MCP server that provides LLMs with essential random generation abilities, including random integers, floats, choices, shuffling, and cryptographically secure tokens.
      7
      156 PyPI
      50
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Generates random integers within a specified range and random alphanumeric strings of specified length through MCP protocol integration.
      2
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An encrypted and secure random number generation server that complies with the MCP protocol, suitable for AI applications, LLMS, and other systems that require high-quality random numbers.
      7
      2
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      MCP server providing true randomness capabilities to Claude, enabling cryptographically secure random number generation for games, decision-making, sampling, simulations, and any operation requiring genuine randomness.
      13
      2
      MIT