Dice Roller MCP Server

A Model Context Protocol (MCP) server that provides dice rolling, coin flipping,and full DnD/tabletop RPG mechanics for AI assistants.

Purpose

This MCP server gives Claude (or any MCP-compatible AI) the ability to roll dice,flip coins, and run tabletop RPG mechanics in real-time with true randomness.

Features

flip_coin - Flip one or more coins, get Heads/Tails results
roll_dice - Roll using standard NdM+K notation (e.g. 2d6, 1d20+5, 4d8-2)
roll_advantage - Roll with advantage (2x, take higher) for DnD 5e
roll_disadvantage - Roll with disadvantage (2x, take lower) for DnD 5e
roll_stats - Generate a full DnD character stat block (4d6 drop lowest x6)
roll_initiative - Roll initiative (1d20 + modifier) for DnD combat
roll_custom - Roll any count/sides/modifier combo with an optional label
roll_percentile - Roll a percentile die (d100)
roll_drop_lowest - Roll NdM and drop the lowest result

Prerequisites

Docker Desktop with MCP Toolkit enabled
Docker MCP CLI plugin (docker mcp command)

Installation

See INSTALLATION section at the bottom of this file, or follow the numbered stepsprovided when you received these files.

Usage Examples

In Claude Desktop, you can ask:

"Roll a d20 with +5 modifier"
"Flip 3 coins"
"Roll 2d6+3 for damage"
"Roll my DnD character stats"
"Roll initiative with +2 dex"
"Roll with advantage on a d20"
"Roll 4d6 drop lowest for strength"
"Roll a percentile die"
"Roll 3d8 for my fireball damage, label it Fireball"

Architecture

Claude Desktop -> MCP Gateway -> Dice Roller MCP Server (Docker)

No external API or secrets needed. Pure Python random module.

Development

Local Testing

# Run directly (no Docker needed for testing)
python dice_roller_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python dice_roller_server.py

Adding New Tools

Add an async function to dice_roller_server.py
Decorate with @mcp.tool()
Single-line docstring only
All params default to empty string ""
Return a formatted string
Add tool name to custom.yaml catalog
Rebuild Docker image: docker build -t dice-roller-mcp-server .

Troubleshooting

Tools not appearing? Verify Docker image built, check catalog/registry files, restart Claude Desktop.
Gateway panic? Ensure all docstrings are single-line only.
Wrong results? All randomness uses Python's secrets-seeded random — it's fair!

Security

No API keys required
Running as non-root user in Docker
No network access needed

License

MIT License

Dice Roller MCP Server