Provides dice rolling and coin flipping functionality for AI assistants
š² Dice MCP Server
A Model Context Protocol (MCP) server that provides dice rolling and coin flipping functionality for AI assistants like Claude.
What is MCP?
The Model Context Protocol (MCP) is an open standard that allows AI assistants to securely connect to external tools and data sources. Think of it as a universal adapter that lets Claude use custom tools you create.
MCP servers run in Docker containers, providing:
- Isolation ā Secure sandboxed environment
- Portability ā Works on any system with Docker
- Standardization ā Consistent protocol across all tools
How MCP Communication Works
MCP uses JSON-RPC 2.0 over stdio (standard input/output). Communication happens through a structured conversation between the client (Claude Desktop) and your server.
The 3-Step Handshake
Before any tools can be used, the client and server must complete an initialization handshake:
Step 1: Initialize (Client ā Server)
{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":0}
"Hey server, I'm a client. Here's my protocol version and capabilities."
The server responds with its own capabilities and version info.
Step 2: Initialized Notification (Client ā Server)
{"jsonrpc":"2.0","method":"notifications/initialized"}
"Got it! We're connected and ready to work."
Step 3: List Tools (Client ā Server)
{"jsonrpc":"2.0","method":"tools/list","id":1}
"What tools do you have available?"
The server responds with all available tools, their parameters, and descriptions.
Visual Flow
āāāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāāā
ā Claude Desktop ā ā Your MCP Server ā
ā (Client) ā ā (dice-mcp) ā
āāāāāāāāāā¬āāāāāāāāāā āāāāāāāāāā¬āāāāāāāāāā
ā ā
ā 1. initialize ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā>ā
ā ā
ā Response: capabilities ā
ā<āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā 2. notifications/initialized ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā>ā
ā ā
ā 3. tools/list ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā>ā
ā ā
ā Response: [roll_dice, roll_multiple, ā
ā coin_flip] ā
ā<āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
ā ā
ā 4. tools/call (when you ask Claude) ā
āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā>ā
ā ā
ā Response: "š² Rolled d20: 17" ā
ā<āāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāāā
Why Docker + stdio?
| Component | Purpose |
|---|---|
| Docker | Isolated container for security and portability |
| stdio | Communication via stdin/stdout pipes |
-i flag |
Keeps stdin open so messages can flow both ways |
--rm flag |
Automatically remove container when it exits |
Claude Desktop handles all of this automatically ā you just say "roll a d20" and it manages the JSON-RPC behind the scenes!
Available Tools
| Tool | Parameters | Description |
|---|---|---|
roll_dice |
sides (default: "6") |
Roll a single die with configurable sides |
roll_multiple |
count (default: "2"), sides (default: "6") |
Roll multiple dice and get total |
coin_flip |
None | Flip a coin for heads or tails |
Common Dice Notation
| Dice | Sides | Common Use |
|---|---|---|
| d4 | 4 | Damage dice |
| d6 | 6 | Standard dice |
| d8 | 8 | Weapon damage |
| d10 | 10 | Percentile |
| d12 | 12 | Barbarian damage |
| d20 | 20 | Attack rolls, skill checks |
| d100 | 100 | Percentile rolls |
Prerequisites
- Docker Desktop with MCP Toolkit enabled
- Docker MCP
Tools (3)
roll_diceRoll a single die with configurable sidesroll_multipleRoll multiple dice and get totalcoin_flipFlip a coin for heads or tailsConfiguration
{"mcpServers":{"dice":{"command":"docker","args":["run","-i","--rm","aaronmeis/dice-mcp"]}}}