https://github.com/yamaton/mcp-dice
A MCP server enabling LLMs to roll dice
https://github.com/yamaton/mcp-dice
Last synced: about 1 month ago
JSON representation
A MCP server enabling LLMs to roll dice
- Host: GitHub
- URL: https://github.com/yamaton/mcp-dice
- Owner: yamaton
- License: mit
- Created: 2024-12-03T15:34:13.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-01-01T23:16:31.000Z (6 months ago)
- Last Synced: 2025-03-31T01:51:19.732Z (3 months ago)
- Language: Python
- Size: 35.2 KB
- Stars: 1
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- mcp-index - Dice Roller - Rolls dice using standard notation and returns results with their total sum, including individual roll outcomes. (Gaming and Game Development)
README
# mcp-dice: A MCP Server for Rolling Dice
[](https://smithery.ai/protocol/mcp-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
### Installing via Smithery
To install Dice Roller for Claude Desktop automatically via [Smithery](https://smithery.ai/protocol/mcp-dice):
```bash
npx @smithery/cli install mcp-dice --client claude
```
Make `uv` available: https://docs.astral.sh/uv/getting-started/installation/
## Usage
### Basic Command Line Usage
```shell
# Using uvx
uvx mcp-dice
```
### Input Format
The server accepts a JSON object with a `notation` field:
```json
{
"notation": "2d6+3"
}
```
Example responses:
```json
{
"rolls": [
3,
1
],
"sum": 4,
"modifier": 3,
"total": 7,
"notation": "2d6+3",
"timestamp": "2024-12-03T16:36:38.926452"
}
```
## Claude Desktop Configuration
### Location
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%/Claude/claude_desktop_config.json`
### Examples
macOS Configuration
```json
{
"mcpServers": {
"dice": {
"command": "uvx",
"args": ["mcp-dice"]
}
}
}
```
WSL Configuration
```json
{
"mcpServers": {
"dice": {
"command": "wsl",
"args": [
"-e",
"zsh",
"-lc",
"uvx mcp-dice"
]
}
}
}
```
Note: Replace `zsh` with your login shell.
## Development and Debugging
### Installing Development Dependencies
```shell
# Clone the repository
git clone https://github.com/yourusername/mcp-dice
cd mcp-dice
# Install development dependencies
uv pip install -e ".[dev]"
```
### Running Tests
```shell
uv run pytest
```
### Using MCP Inspector
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a useful tool for debugging your MCP server. Install and run it using npm:
```shell
npx @modelcontextprotocol/inspector uvx mcp-dice
```
### Claude Desktop Configuration for Development
macOS configuration (local dev)
```json
{
"mcpServers": {
"dice": {
"command": "uv",
"args": [
"run",
"--directory",
"path/to/mcp-dice-repo",
"mcp-dice"
]
}
}
}
```
Note: Replace `path/to/mcp-dice-repo` with the path to the repository on your filesystem.
Windows (WSL) configuration (local dev)
```json
{
"mcpServers": {
"dice": {
"command": "wsl",
"args": [
"-e",
"zsh",
"-lc",
"uv run --directory path/to/mcp-dice-repo mcp-dice"
]
}
}
}
```
Note: Replace `zsh` with your login shell. Also, replace `path/to/mcp-dice-repo` with the path to the repository on your WSL filesystem.