# Dice Roller MCP Server

A Model Context Protocol (MCP) server that provides random dice rolling capabilities for AI assistants.

## Purpose

This MCP server provides a simple, deterministic interface for AI assistants to generate random numbers simulating tabletop dice rolls.

## Features

### Current Implementation
- `roll_die` - Roll a single die with N sides (defaults to standard 6-sided die)
- `roll_multiple` - Roll multiple dice at once and get the total and individual results (e.g., 2d20 for advantage)

## Prerequisites

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

## Installation

🚀 Installation Guide
This server is designed to be installed via standard Docker MCP Gateway, allowing it to run alongside other local servers (like Obsidian or local file access).

Step 1: Clone & Build
Download standard repository and build standard Docker container image.

Bash

git clone https://github.com/endikoci02/dice-roller-mcp.git
cd dice-roller-mcp
docker build -t dice-roller-mcp-server .


Step 2: Register the Server
You need to tell standard local Docker MCP installation about this new server.

Create or Edit your Custom Catalog:

Windows: %USERPROFILE%\.docker\mcp\catalogs\custom.yaml

macOS/Linux: ~/.docker/mcp/catalogs/custom.yaml

Add the Catalog Entry: Add this block to custom.yaml (ensure indentation is correct):

YAML

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  dice-roller:
    type: server
    image: dice-roller-mcp-server:latest
    tools:
      - name: roll_die
      - name: roll_multiple
    metadata:
      category: utilities

      
Enable in Registry: Open standard registry.yaml file (located one folder up from standard catalogs folder) and add standard server under standard registry: key:

YAML

registry:
  dice-roller:
    ref: ""

    
Step 3: Configure Claude Desktop
Update your Claude Desktop configuration to use standard Docker Gateway.

Open your config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Ensure standard mcp-toolkit-gateway is in your mcpServers list. ⚠️ Important: Replace /PATH/TO/YOUR/HOME with your actual absolute home directory path.

JSON

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/PATH/TO/YOUR/HOME/.docker/mcp:/mcp",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--transport=stdio"
      ]
    }
  }
}
Restart Claude Desktop completely.

##note for windows installation make sure to use // on the path 


Verify Registration

Bash

docker mcp server list

# Test a Roll
You can test standard server without Claude by using standard Docker MCP CLI in your terminal:

Bash: 

docker mcp call dice-roller roll_die '{"sides": "20"}'
Output: 🎲 Rolled a d20: 15

## Usage Examples

In Claude Desktop, you can ask:
- "Roll a d20 for me"
- "Roll 4d6 and drop the lowest" (The AI will use roll_multiple and process the result)
- "Flip a coin" (The AI can interpret this as rolling a d2)
- "Roll damage for a fireball (8d6)"

## Architecture

Claude Desktop → MCP Gateway → Dice Roller MCP Server → Python random module

## License

MIT License