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 steps provided 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

1. Add an async function to dice_roller_server.py
2. Decorate with @mcp.tool()
3. Single-line docstring only
4. All params default to empty string ""
5. Return a formatted string
6. Add tool name to custom.yaml catalog
7. 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