mcp-dice: A MCP Server for Rolling Dice

A Model Context Protocol (MCP) server that enables Large Language Models (LLMs) to roll dice. It accepts standard dice notation (e.g., `1d20`) and returns both individual rolls and their sum.

Features

• Supports standard dice notation (e.g., `1d20`, `3d6`, `2d8+1`)
• Returns both individual rolls and the total sum
• Easy integration with Claude Desktop
• Compatible with MCP Inspector for debugging

Installation

1. Clone the Repository:

git clone https://github.com/pashpashpash/mcp-dice.git
   cd mcp-dice

2. Set up Python Environment:

python -m venv venv
   source venv/bin/activate  # On Windows, use: venv\Scripts\activate

3. Install Dependencies:

pip install -e .

4. Install Development Dependencies (optional):

pip install -e ".[dev]"

Usage

Input Format

The server accepts a JSON object with a `notation` field:

{
  "notation": "2d6+3"
}

Example responses:

{
  "rolls": [
    3,
    1
  ],
  "sum": 4,
  "modifier": 3,
  "total": 7,
  "notation": "2d6+3",
  "timestamp": "2024-12-03T16:36:38.926452"
}

Claude Desktop Configuration

Configuration File Location

• macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
• Windows: `%APPDATA%/Claude/claude_desktop_config.json`

Basic Configuration

{
  "mcpServers": {
    "dice": {
      "command": "python",
      "args": ["-m", "mcp_dice"],
      "cwd": "path/to/mcp-dice"
    }
  }
}

Note: Replace "path/to/mcp-dice" with the actual path to your cloned repository.

WSL Configuration

{
  "mcpServers": {
    "dice": {
      "command": "wsl",
      "args": [
        "-e",
        "python",
        "-m",
        "mcp_dice"
      ],
      "cwd": "path/to/mcp-dice"
    }
  }
}

Note: Adjust the path according to your WSL filesystem.

Development and Debugging

Running Tests

pytest

Using MCP Inspector

The MCP Inspector is a useful tool for debugging your MCP server:

cd path/to/mcp-dice
npx @modelcontextprotocol/inspector python -m mcp_dice

View logs with:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

License

Licensed under MIT - see LICENSE file.

Note: This is a fork of the original mcp-dice repository.