mcp-dice: A MCP Server for Rolling Dice

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.