home / mcp / dice rolling mcp server

Dice Rolling MCP Server

A TypeScript-based Model Context Protocol (MCP) server providing comprehensive dice rolling capabilities with advanced gaming mechanics

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "jimmcq-dice-rolling-mcp": {
      "url": "https://dice-rolling-mcp.vercel.app/mcp"
    }
  }
}

This MCP server provides cryptographically secure dice rolling for AI assistants through a simple, standards-compliant interface. It supports standard and advanced dice mechanics, giving your AI-powered workflows true randomness for gaming, simulations, and decision-making that requires reliable probability results.

How to use

You connect an MCP client to either a remote HTTP endpoint or a local STDIO server to start making dice rolls. When you prompt your AI with a dice expression, the server parses the notation, computes results using secure random numbers, and returns a structured result you can display or analyze. You can use standard notation like 3d6+2, add modifiers, combine dice types, and apply advanced mechanics such as advantage, exploding dice, rerolls, and success counting. Tools are available to search for dice operations, fetch detailed topics, and execute or validate rolls.

How to install

# Prerequisites
node >= 18
npm >= 6

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

Additional configuration and usage notes

There are two primary methods to connect to this MCP server: a remote HTTP endpoint for streams over the network, and a local STDIO configuration suitable for desktop integrations. Use the remote path when your client supports HTTP MCP connections. Use the local STDIO path when you run the server on your machine and want to connect via a local I/O channel.

Remote HTTP endpoint (production URL): use this URL in your MCP client configuration to connect over HTTP.

Local STDIO configuration (for Claude Desktop or similar clients) uses a command that runs the MCP server locally and communicates via standard input/output.

Security and reliability notes

The server uses cryptographically secure randomness for all dice results, preventing predictability and ensuring gaming integrity. It validates inputs to reject malformed expressions and enforces resource limits to avoid excessive computation. The architecture is modular to support future dice mechanics and maintains strict type safety with TypeScript.

Examples

Basic roll: Roll 3d6+2 for damage.

Advantage roll: Roll 2d20kh1 (keep highest) with a modifier.

Discovery and integration with MCP clients

Two integration methods are supported: a remote HTTP transport and a local STDIO transport. The remote endpoint is exposed for production use, while the local STDIO flow is suitable for desktop clients that launch the MCP server as a child process.

Notes on testing and development

A complete test suite validates notation parsing, execution with mocked randomness, edge cases, and MCP protocol readiness. Development builds produce a dist output that can be started in standalone mode.

Available tools

search

Discovers available dice rolling operations and documentation. Enables integration with chat assistants and remote MCP clients.

fetch

Retrieves detailed content for a specific topic by ID, enabling rich UI rendering and programmatic access to topics.

dice_roll

Executes dice rolls using standard notation with optional labeling and verbose output. Returns both human-readable results and structured data.

dice_validate

Validates dice notation without rolling, providing a structured breakdown of the expression and any errors.