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:

• `content`: JSON with search results containing `id`, `title`, and `url` fields
• `structuredContent`: Machine-readable search results with relevance scoring

`fetch`

Retrieves detailed content for a specific dice rolling topic by ID.

Parameters:

• `id` (required): Topic ID from search results

Returns:

• `content`: JSON document with full content
• `structuredContent`: Metadata and structured document information

`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

Returns:

• `content`: Human-readable text with roll results and emojis
• `structuredContent`: Complete roll data including:
  • `notation`: Original dice notation
  • `total`: Final result
  • `rolls`: Individual die results with metadata (dropped, exploded, etc.)
  • `breakdown`: Mathematical breakdown string
  • `critical`: Critical success/fail detection for d20 rolls
  • `modifier`: Applied modifiers
  • `timestamp`: ISO timestamp of the roll

`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

Returns:

• `content`: Human-readable validation result
• `structuredContent`: Structured validation data including:
  • `valid`: Boolean validation status
  • `expression`: Parsed dice expression (if valid)
  • `breakdown`: Structured breakdown of dice and modifiers
  • `error`: Error message (if invalid)

Structured Content Support

All tools return both human-readable `content` and machine-readable `structuredContent` following the OpenAI Apps SDK specification. This enables:

• Programmatic access to roll results and validation data
• Component templates for rich UI rendering (future enhancement)
• Integration with AI workflows requiring structured data
• Advanced features like roll history, statistics, and visualizations

The structured content includes complete metadata about each operation, making it suitable for building advanced applications on top of the dice rolling capabilities.

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

1. Extend the `DiceTerm` interface in `types.ts`

2. Update the parser regex in `dice-notation-parser.ts`

3. Implement the mechanic in `dice-roller.ts`

4. 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

Links

• Repository: https://github.com/jimmcq/dice-rolling-mcp
• Live Demo: https://dice-rolling-mcp.vercel.app
• MCP Endpoint: https://dice-rolling-mcp.vercel.app/mcp

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