Dice Rolling MCP Server

A comprehensive TypeScript-based Model Context Protocol (MCP) server that provides advanced dice rolling capabilities for AI assistants. Perfect for tabletop gaming, RPGs, and any application requiring sophisticated random number generation with gaming mechanics.

The Problem: LLMs Can't Actually Roll Dice

When you ask an AI assistant to "roll dice," they don't actually roll anything. Large Language Models are deterministic systems that generate responses based on patterns in their training data. When asked to roll a d20, they might respond with something like "I rolled a 14" - but that number was generated through text prediction, not random number generation.

This creates several problems:

No True Randomness: Results aren't genuinely random and may follow predictable patterns
Gaming Integrity: Critical for tabletop RPGs where fair dice rolls affect gameplay
Simulation Accuracy: Statistical simulations require proper random number generation
Reproducibility Issues: Same prompts might yield suspiciously similar "random" results

The Solution: Real Dice for AI

This MCP server acts as a bridge between AI assistants and actual random number generation. Think of it as giving your AI assistant a real set of dice instead of asking them to imagine rolling.

How it works:

AI assistant receives dice notation (e.g., "3d6+2")
MCP server parses the request and generates cryptographically secure random numbers
Real dice mechanics are applied (advantage, exploding dice, rerolls, etc.)
Genuine random results are returned to the AI

The result: AI assistants can now provide truly random dice rolls with mathematical integrity, making them suitable for actual gaming, simulations, and any application requiring authentic randomness.

Features

Standard Dice Notation

Basic rolls: 1d20, 3d6, 2d10
Modifiers: 1d20+5, 2d6-3
Multiple dice types: 1d20+2d6+3
Percentile dice: 1d% (d100)
Fudge dice: 4dF (Fate/Fudge system)

Advanced Mechanics

Advantage/Disadvantage: 2d20kh1 (keep highest), 2d20kl1 (keep lowest)
Drop mechanics: 4d6dl1 (drop lowest), 4d6dh1 (drop highest)
Exploding dice: 3d6! (reroll and add on maximum)
Reroll mechanics: 4d6r1 (reroll 1s)
Success counting: 5d10>7 (count successes ≥7)

MCP Tools

`search`

Discovers available dice rolling operations and documentation. Required for ChatGPT Connector compatibility.

Parameters:

query (required): Search query to find relevant dice rolling information

Returns: JSON with search results containing id, title, and url fields as per OpenAI MCP specification.

`dice_roll`

Executes dice rolls using standard notation with optional labeling and verbose output.

Parameters:

notation (required): Dice notation string (e.g., "3d6+2")
label (optional): Descriptive label for the roll
verbose (optional): Show detailed breakdown of individual dice

`dice_validate`

Validates dice notation without executing the roll, providing detailed breakdown of what the notation means.

Parameters:

notation (required): Dice notation string to validate

Remote MCP Integration (Streamable HTTP)

This MCP server supports Streamable HTTP transport for remote connections and implements the OpenAI MCP specification, including the required search tool for operation discovery.

Compatible With:

Claude Remote MCP Connectors (and Claude Desktop)
ChatGPT Connectors (currently only in Developer Mode)
Any MCP client supporting Streamable HTTP transport

Connection Endpoints:

Local Development: http://localhost:3000/mcp
Production: https://dice-rolling-mcp.vercel.app/mcp

The search and fetch tools enable both Claude and ChatGPT to discover available dice rolling operations automatically.

Local MCP Integration (STDIO)

For local Claude Desktop integration, configure your claude_desktop_config.json:

{
  "mcpServers": {
    "dice-rolling-remote": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-stdio", 
        "connect", 
        "https://dice-rolling-mcp.vercel.app/mcp"
      ]
    }
  }
}

Local Installation

git clone https://github.com/jimmcq/dice-rolling-mcp
cd dice-rolling-mcp
npm install
npm run build

Usage

With Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "dice-roller": {
      "command": "node",
      "args": ["path/to/dice-rolling-mcp/dist/index.js"]
    }
  }
}

Platform-specific examples:

Windows (WSL):

{
  "mcpServers": {
    "dice-roller": {
      "command": "wsl",
      "args": ["node", "/path/to/dice-rolling-mcp/dist/index.js"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "dice-roller": {
      "command": "node",
      "args": ["/path/to/dice-rolling-mcp/dist/index.js"]
    }
  }
}

Standalone Server

npm run start

Examples

Basic Rolling

Human: Roll 3d6+2 for damage
Assistant: You rolled 3d6+2 for damage:
🎲 Total: 13
📊 Breakdown: 3d6:[4,2,5] + 2

Advantage System

Human: Roll 2d20kh1+5 for attack with advantage
Assistant: You rolled 2d20kh1+5 for attack with advantage:
🎲 Total: 23
📊 Breakdown: 2d20:[12,18] keep highest + 5

Validation

Human: Is "4d6kh3+2d8+5" valid dice notation?
Assistant: ✅ Valid dice notation: 4d6kh3+2d8+5

Breakdown:
• 4d6 (keep highest 3)
• 2d8
• Modifier: +5

Discovery (Remote MCP Integration)

Human: What dice operations are available?
Assistant: [Calls search tool with query "dice"]
🎲 Found dice rolling operations:
- Basic Dice Notation: Learn standard XdY format
- D&D Advantage and Disadvantage: 2d20kh1 mechanics
- Combat Roll Examples: Attack, damage, spells
- Ability Score Generation: 4d6kh3 for character stats

Architecture

Core Components

Parser (src/parser/): Tokenizes and parses dice notation using regex-based parsing
Roller (src/roller/): Executes dice expressions with cryptographically secure random number generation
MCP Server (src/index.ts): Implements the Model Context Protocol for AI assistant integration
Type System (src/types.ts): Comprehensive TypeScript definitions for all dice mechanics

Key Design Decisions

Security: Uses Node.js crypto.randomInt() for cryptographically secure randomness
Extensibility: Modular architecture supports easy addition of new dice mechanics
Compatibility: ES2022 target with fallbacks for broader Node.js version support
Type Safety: Full TypeScript implementation with strict type checking

Testing

npm test

The test suite covers:

Dice notation parsing for all supported mechanics
Roll execution with mocked random number generation
Edge cases and error handling
MCP protocol compliance

Development

Project Structure

dice-rolling-mcp/
├── src/
│   ├── index.ts              # MCP server implementation
│   ├── parser/               # Dice notation parser
│   ├── roller/               # Dice rolling engine
│   ├── statistics/           # Statistical analysis tools
│   └── types.ts              # TypeScript definitions
├── __tests__/                # Test suite
├── dist/                     # Compiled JavaScript
└── examples/                 # Usage examples

Adding New Mechanics

Extend the DiceTerm interface in types.ts
Update the parser regex in dice-notation-parser.ts
Implement the mechanic in dice-roller.ts
Add comprehensive tests

Configuration

The server supports various configuration options through the DiceRollerConfig interface:

Maximum dice count per roll
Maximum die size
Random number source selection
History size limits

Technical Specifications

Language: TypeScript 5.8+
Runtime: Node.js 18+ (tested with v24.0.2)
Protocol: MCP (Model Context Protocol) 2024-11-05
OpenAI Compatibility: Implements OpenAI MCP specification with required search tool
Transport Support: STDIO (local Claude Desktop) + Streamable HTTP (remote connections)
Dependencies: Minimal (zod, @modelcontextprotocol/sdk, @vercel/mcp-adapter)
Module System: ES Modules
Test Framework: Jest with ts-jest

Security Considerations

Input validation prevents malicious dice expressions
Resource limits prevent DoS through extremely large rolls
Cryptographically secure random number generation
No external network dependencies

Author

Jim McQuillan

GitHub: https://github.com/jimmcq
LinkedIn: https://www.linkedin.com/in/jimmcquillan/

License

ISC

Contributing

Contributions welcome! Please ensure:

All tests pass (npm test)
Code follows existing patterns and conventions
New features include appropriate test coverage
TypeScript strict mode compliance

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Provides cryptographically secure random dice rolls for AI assistants, supporting standard and advanced dice notation for tabletop RPGs and games.

Related MCP Servers

mcp-dice
yamaton
A
security
A
license
A
quality
A MCP server enabling LLMs to roll dice
Last updated -
1
1
MIT License
MCP Rand
turlockmike
A
security
A
license
A
quality
Provides random number generation utilities, including a secure UUID generator powered by Node's crypto module.
Last updated -
7
34
3
MIT License
Coin Flip MCP Server
TeglonLabs
A
security
F
license
A
quality
Enables interaction with a tool for generating true random coin flips via random.org's API, supporting multiple custom side configurations and illustrating the Model Context Protocol.
Last updated -
1
ID Generator MCP
devstacks-software-engineering
A
security
A
license
A
quality
Provides AI assistants with capabilities to generate collision-resistant unique identifiers using UUID v4 and CUID2 algorithms.
Last updated -
1
8
1
MIT License

View all related MCP servers