Dice Roller MCP Server
A Model Context Protocol (MCP) server that provides random dice rolling capabilities for AI assistants.
Purpose
This MCP server provides a simple, deterministic interface for AI assistants to generate random numbers simulating tabletop dice rolls.
Features
Current Implementation
roll_die- Roll a single die with N sides (defaults to standard 6-sided die)roll_multiple- Roll multiple dice at once and get the total and individual results (e.g., 2d20 for advantage)
Prerequisites
- Docker Desktop with MCP Toolkit enabled
- Docker MCP CLI plugin (
docker mcpcommand)
Installation
🚀 Installation Guide This server is designed to be installed via standard Docker MCP Gateway, allowing it to run alongside other local servers (like Obsidian or local file access).
Step 1: Clone & Build Download standard repository and build standard Docker container image.
Bash
git clone https://github.com/endikoci02/dice-roller-mcp.git cd dice-roller-mcp docker build -t dice-roller-mcp-server .
Step 2: Register the Server You need to tell standard local Docker MCP installation about this new server.
Create or Edit your Custom Catalog:
Windows: %USERPROFILE%\.docker\mcp\catalogs\custom.yaml
macOS/Linux: ~/.docker/mcp/catalogs/custom.yaml
Add the Catalog Entry: Add this block to custom.yaml (ensure indentation is correct):
YAML
version: 2 name: custom displayName: Custom MCP Servers registry: dice-roller: type: server image: dice-roller-mcp-server:latest tools:
- name: roll_die
- name: roll_multiple
metadata: category: utilities
Enable in Registry: Open standard registry.yaml file (located one folder up from standard catalogs folder) and add standard server under standard registry: key:
YAML
registry: dice-roller: ref: ""
Step 3: Configure Claude Desktop Update your Claude Desktop configuration to use standard Docker Gateway.
Open your config file:
Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Ensure standard mcp-toolkit-gateway is in your mcpServers list. ⚠️ Important: Replace /PATH/TO/YOUR/HOME with your actual absolute home directory path.
JSON
{ "mcpServers": { "mcp-toolkit-gateway": { "command": "docker", "args": [ "run", "-i", "--rm", "-v", "/var/run/docker.sock:/var/run/docker.sock", "-v", "/PATH/TO/YOUR/HOME/.docker/mcp:/mcp", "docker/mcp-gateway", "--catalog=/mcp/catalogs/custom.yaml", "--config=/mcp/config.yaml", "--registry=/mcp/registry.yaml", "--transport=stdio" ] } } } Restart Claude Desktop completely.
##note for windows installation make sure to use // on the path
Verify Registration
Bash
docker mcp server list
Test a Roll
You can test standard server without Claude by using standard Docker MCP CLI in your terminal:
Bash:
docker mcp call dice-roller roll_die '{"sides": "20"}' Output: 🎲 Rolled a d20: 15
Usage Examples
In Claude Desktop, you can ask:
- "Roll a d20 for me"
- "Roll 4d6 and drop the lowest" (The AI will use roll_multiple and process the result)
- "Flip a coin" (The AI can interpret this as rolling a d2)
- "Roll damage for a fireball (8d6)"
Architecture
Claude Desktop → MCP Gateway → Dice Roller MCP Server → Python random module
License
MIT License
