Skip to main content
Glama
greatoldcactus

random-mcp

by greatoldcactus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

Random MCP

A local Python MCP server for pseudorandom sampling. Uses the official MCP Python SDK.

Install and run

Requires Python 3.10 or newer. From this directory:

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'
.venv/bin/random-mcp

The server communicates over stdio and waits for an MCP client. It also supports python -m random_mcp from the environment where it is installed. On Windows, use .venv\Scripts\python.exe and .venv\Scripts\random-mcp.exe.

Configure your MCP host with an absolute path to the installed command:

{
  "mcpServers": {
    "random": {
      "command": "/absolute/path/to/random-mcp/.venv/bin/random-mcp",
      "args": []
    }
  }
}

Related MCP server: Random Value MCP Server

Tools

  • random_number() returns {"value": 0.375}: one uniform float in [0, 1).

  • random_interval(minimum, maximum, kind="float") returns {"value": ...}. Choose "integer" for whole numbers, with both endpoints included. Float sampling follows Python's random.uniform; rounding can include the upper endpoint. Equal bounds return that value. Reversed bounds, non-finite values, fractional integer bounds, and non-finite sampling results produce tool errors.

  • random_normal(mean=0, standard_deviation=1) returns {"value": ...} from a normal distribution. Both parameters must be finite; standard deviation must be positive. Non-finite results produce tool errors.

Values shown are examples. Sampling uses Python's standard pseudorandom generator, without public seed parameters. Each number call returns one sample.

Dice

roll_dice(expression, detail="auto") accepts NdM, such as 1d10, 2d10, or 100d10, and sums such as 1d10 + 2d100 + 5d4. Each die is sampled independently from 1 through M, inclusive. Whitespace, uppercase D, and leading zeros are accepted. Counts and sides must be positive integers. Only addition is supported: modifiers, subtraction, multiplication, and parentheses are rejected. Terms remain in input order.

  • auto: include individual rolls for up to 100 total dice; use compact above 100.

  • full: always include individual rolls.

  • compact: return aggregates without individual rolls or roll arrays in memory.

For example, roll_dice("1000d4") returns this shape (totals vary):

{
  "expression": "1000d4",
  "detail": "compact",
  "total_dice": 1000,
  "total": 2500,
  "terms": [{"count": 1000, "sides": 4, "subtotal": 2500}]
}

Full mode adds a rolls array to each term. Auto considers the total count across all terms. Limits are 10,000 total dice, 100 terms, 1,000,000 sides per die, and 10,000 expression characters. Invalid requests return tool errors before any dice are rolled.

Development

Install the development tools with python -m pip install -e '.[dev]' using the virtual environment's Python. Run all checks before committing:

.venv/bin/python -m ruff check .
.venv/bin/python -m ruff format --check .
.venv/bin/python -m mypy
.venv/bin/python -m pytest

Apply automatic lint fixes and formatting with:

.venv/bin/python -m ruff check --fix .
.venv/bin/python -m ruff format .

Ruff checks application code and tests for common errors, import ordering, and consistent formatting, with Python 3.10 as the target. Mypy runs in strict mode on src; pytest covers sampling, dice parsing, MCP validation, and stdio calls. Tool settings live in pyproject.toml.

Features are delivered in five commits: uniform sampling, intervals, normal sampling, simple dice, then compound dice. Each stage includes tests and docs.

Available Tools

4 tools
random_intervalA

Sample uniformly between bounds; kind='integer' includes both endpoints.

Float sampling can include the upper bound through rounding. Equal bounds return that value. Integer bounds must be whole numbers.

ParametersJSON Schema
NameRequiredDescriptionDefault
kindNofloat
maximumYes
minimumYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
valueYes

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations provided, so the description carries the full burden. It discloses important edge behaviors: integer includes both endpoints, float may include upper bound due to rounding, equal bounds return that value, and integer bounds must be whole numbers. This is good context, but it lacks details on error handling for invalid bounds (e.g., min > max) or the exact distribution (uniform is stated). It is above average but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and structured: three short sentences. It starts with the core functionality, then provides important edge case details. Every sentence adds value. It could be slightly more structured with bullet points for edge cases, but it is efficient and front-loaded with the main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple with 3 parameters elementary types. The description covers the key behavioral aspects: sampling uniform, handling of endpoints, equal bounds, and integer bounds constraints. With an output schema present, it doesn't need to explain return values. Potential missing pieces include error handling for invalid ranges (e.g., min > max) and note that the tool does not support other distributions, but given the simplicity, the description is reasonably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning the schema provides no description for the parameters (minimum, maximum, kind). The description compensates by explaining the meaning of kind (integer includes endpoints, float may include upper bound), and that equal bounds return that value, and integer bounds must be whole numbers. However, it does not explain the semantics of minimum and maximum beyond being bounds, but that is self-evident from their names. Given the 0% coverage, the description does a good job of adding necessary semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that it samples uniformly between bounds, with a kind parameter for integer or float. It distinguishes itself from siblings by explaining the interval sampling behavior, though it could explicitly mention that it's a uniform distribution, which is implied. Given the sibling tools (random_number, random_normal, roll_dice), the description is clear enough about its purpose and domain.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains the behavior of sampling between bounds and the kind parameter, but it does not explicitly state when to use this tool over its siblings, such as random_number, random_normal, or roll_dice. It implies use for uniform random values in an interval, but does not provide explicit exclusions or alternatives. This is a moderate gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

random_normalA

Return one normal sample; defaults to mean 0 and standard deviation 1.

Parameters must be finite and standard_deviation must be positive.

ParametersJSON Schema
NameRequiredDescriptionDefault
meanNo
standard_deviationNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
valueYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the behavioral disclosure burden. It adds non-obvious constraints: parameters must be finite and standard_deviation must be positive. It also states the defaults (0 and 1), covering the main edge cases for a sampling tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences: the first states behavior and defaults, the second states parameter constraints. There is no filler and no repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with no required parameters and an output schema, the description supplies the distribution, defaults, and validity constraints needed to call it correctly. It does not explain return values, which is acceptable because an output schema exists. Missing explicit sibling routing is a minor gap given the low complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It conveys parameter meanings through the defaults and adds constraints ('finite', 'standard_deviation must be positive') that are not in the schema. The parameter names mean and standard_deviation are self-explanatory, and the added constraints make invocation safe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the exact operation ('Return one normal sample') and the distribution, distinguishing it from siblings such as roll_dice and random_interval. It also specifies defaults for mean and standard deviation, making the tool's behavior unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given about when to use this tool versus random_number, random_interval, or roll_dice. The only usage signal is the statistical operation itself, which is implied rather than explicitly stated. An agent must infer appropriateness from the name and description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

random_numberA

Return one uniformly distributed random float in [0, 1).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
valueYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explicitly states that the result is one float, uniformly distributed, and in [0, 1), which covers the key behavioral traits for a zero-parameter random-number tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, compact sentence with no filler. The essential facts—one, uniformly distributed, float, [0, 1)—are all present and clearly ordered.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a no-argument tool with an output schema, the description fully covers the behavior an agent needs to select and invoke it correctly. Nothing significant is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and the input schema confirms an empty properties object. There is no parameter semantics for the description to clarify, so the no-parameter baseline of 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Return') and an exact resource: one uniformly distributed random float in [0, 1). It clearly distinguishes this from siblings like random_interval (range-based) and random_normal (normal distribution) without needing to name them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use or when-not-to-use guidance is provided. The half-open [0, 1) uniform distribution strongly implies the use case, but the agent must infer sibling differentiation from the sibling tool names and this description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

roll_diceA

Roll NdM dice or sums, such as 2d10 or 1d10 + 2d100 + 5d4.

Return count, sides, subtotal per term and a grand total. Full detail also includes every roll; compact omits rolls. Auto uses compact above 100 dice. Only addition is supported; no modifiers, subtraction, or parentheses. Limits: 10,000 total dice, 100 terms, 1,000,000 sides per die, and 10,000 expression characters.

ParametersJSON Schema
NameRequiredDescriptionDefault
detailNoauto
expressionYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
termsYes
totalYes
detailYes
expressionYes
total_diceYes

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavioral traits: it explains return values (count, sides, subtotal, grand total), detail-level behavior (full/compact/auto with auto threshold at 100 dice), support for only addition (no modifiers/subtraction/parentheses), and hard limits (10,000 dice, 100 terms, 1,000,000 sides, 10,000 characters). This is comprehensive and goes beyond what the schema reveals.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficient and well-structured: it opens with the core purpose and an example, then explains return/behavior, then limits. Every sentence adds value, and there is no redundant information. It is front-loaded with the most critical information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with two parameters, an output schema, and clear limits, the description covers all necessary calling context: syntax, return content, detail modes, and constraints. The output schema handles the exact structure, so no additional return-format explanation is needed. An agent can confidently invoke this tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the responsibility of explaining parameters. It thoroughly defines 'expression' with syntax and examples, and explains 'detail' enum values (auto, full, compact) and their behavioral meaning. This fully compensates for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action ('Roll NdM dice or sums') with concrete examples ('2d10', '1d10 + 2d100 + 5d4'). It clearly identifies the resource (dice expressions) and distinguishes itself from siblings like random_number, random_interval, and random_normal by focusing on dice-notation syntax.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly communicates usage context through its detailed explanation of dice notation and supported operations. It does not explicitly name alternatives or exclusion criteria, but the clarity of its scope makes it obvious when to use this tool versus simple random-number generators. Slight gap: no explicit 'use this when...' guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv0.1.0
    • First observedrandom_interval
    • First observedrandom_normal
    • First observedrandom_number
    • First observedroll_dice
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 4 tools

Disambiguation4/5

Each tool targets a distinct distribution or use case: uniform float, bounded interval, normal, and dice notation. random_number and random_interval overlap conceptually since random_number is a special case of uniform sampling, but the descriptions clarify the intended difference.

Naming Consistency4/5

Three tools follow a consistent random_noun pattern, while roll_dice breaks the pattern with a verb_noun style. The naming is still predictable and readable, but the one deviation keeps it from a perfect score.

Tool Count5/5

Four tools is a well-scoped size for a random number generation server. Each tool serves a common random sampling need without unnecessary bloat.

Completeness4/5

The set covers standard uniform, bounded interval, normal, and dice-style generation, which covers most common use cases. Minor gaps like seeding or random choice are absent but not critical for the apparent purpose.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Random Number MCP

    zazencodes
    A
    license
    A
    quality
    A
    maintenance
    Production-ready MCP server that provides LLMs with essential random generation abilities, including random integers, floats, choices, shuffling, and cryptographically secure tokens.
    7
    51
    MIT

  • Random Value MCP Server

    okoshi-f
    F
    license
    B
    quality
    D
    maintenance
    Generates random integers within a specified range and random alphanumeric strings of specified length through MCP protocol integration.
    2
    -

  • MCP Dice Roller

    vandewilly
    A
    license
    A
    quality
    C
    maintenance
    An MCP server that provides tools for rolling dice using standard notation, flipping coins, and selecting random items from lists. It supports advanced tabletop gaming features such as character stat generation and keep-highest/lowest mechanics.
    6
    MIT