Dice Roller MCP Server

A Model Context Protocol (MCP) server that flips coins and rolls dice, including standard dice notation and D&D mechanics.

Purpose

This MCP server gives Claude a simple, dependency-free way to generate random results for tabletop games, D&D sessions, or any "let's leave it to chance" moment.

Related MCP server: Dice Roller MCP Server

Features

Current Implementation

• flip_coin - Flip one or more coins and get Heads/Tails results

• roll_dice - Roll dice using standard notation (e.g. d20, 2d6+3, 4d6-1)

• roll_advantage - Roll 2d20 and keep the higher, D&D advantage mechanic

• roll_disadvantage - Roll 2d20 and keep the lower, D&D disadvantage mechanic

• roll_ability_scores - Generate D&D ability scores (4d6, drop lowest) for one or more stats

Prerequisites

• Docker Desktop with MCP Toolkit enabled

• Docker MCP CLI plugin (docker mcp command)

• No API keys or external services required — this server is fully self-contained

Installation

See the step-by-step instructions provided alongside these files.

Usage Examples

In Claude Desktop, you can ask:

• "Flip a coin"

• "Flip 5 coins"

• "Roll 2d6+3"

• "Roll a d20"

• "Roll with advantage, +5 modifier"

• "Roll with disadvantage"

• "Roll me a set of D&D ability scores"

• "Generate 6 ability scores for a new character"

Architecture

Claude Desktop → MCP Gateway → Dice Roller MCP Server (local, no external calls)

Development

Local Testing

# Run directly
python dice_server.py

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

Adding New Tools

1. Add the function to dice_server.py

2. Decorate with @mcp.tool()

3. Use a single-line docstring and string parameter defaults (param: str = "")

4. Update the catalog entry with the new tool name

5. Rebuild the Docker image

Troubleshooting

Tools Not Appearing

• Verify the Docker image built successfully

• Check catalog and registry files

• Ensure Claude Desktop config includes the custom catalog

• Restart Claude Desktop

Unexpected Errors

• Check container logs with docker logs <container_name>

• Confirm dice notation matches the expected format, e.g. NdM, NdM+K, or NdM-K

Security Considerations

• No API keys or secrets are used by this server

• Running as a non-root user inside the container

• No external network calls are made

License

MIT License