# 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
