# Dice MCP

`dice-mcp` is a local [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for tabletop role-playing dice rolls. It uses Streamable HTTP at `http://127.0.0.1:8000/mcp`.

## Run locally

This project uses [uv](https://docs.astral.sh/uv/). From the repository root, start the server with:

```bash
uv run dice-mcp
```

The server listens only on localhost. Leave it running while using it from an MCP host, then stop it with `Ctrl+C`.

## Tool

### `roll_dice`

Roll one or more dice and add a modifier.

| Parameter | Type | Description |
| --- | --- | --- |
| `sides` | integer | Number of sides on each die. |
| `amount` | integer | Number of dice to roll. |
| `modifier` | integer | Optional value added to the sum of the rolls; defaults to `0`. |
| `exploding` | boolean | Optional; rerolls a die that reaches its maximum value. Defaults to `false`. |

The result contains displayable individual `rolls`, their unmodified `sum`, the `modifier`, and the final `total`. An exploded die is marked with `*`; for example, an exploding d6 result might be `{"rolls": ["6*", "3"], "sum": 9, "modifier": 2, "total": 11}`.

## Dice formulas

The dice utilities also parse conventional dice notation, ready for a formula-based MCP tool:

```python
from dicemcp.dice import parse_formula, roll_formula

parse_formula("2d20+4")
roll_formula("6W6")
```

Both `d`/`D` and the German `W`/`w` separator are supported, as are modifiers such as `d20-1`. An omitted amount means one die.

## Prompts

The server provides MCP prompts for common d20 tabletop workflows:

- `ability_check`
- `saving_throw`
- `attack_roll` (set `advantage=true` for a D&D attack roll that keeps the higher of `2d20`)
- `damage_roll`
- `advantage_roll` (D&D advantage rolls `2d20` and keeps the higher die; set `disadvantage=true` to keep the lower die)

They instruct the model to call `roll_dice` and report the relevant dice and total. They are system-neutral guidance based on familiar d20 conventions.

## Add it to LM Studio

Start the server in a terminal first:

```bash
uv run dice-mcp
```

Then, in LM Studio, open the **Program** tab, choose **Install**, then **Edit mcp.json**. Add this entry inside `mcpServers`:

```json
{
  "dice-mcp": {
    "url": "http://127.0.0.1:8000/mcp"
  }
}
```

Save the configuration, enable the server in a chat, and ask a dice-related question such as: “Make a Dexterity check with a +3 modifier.” LM Studio supports local MCP servers from version 0.3.17 and uses Cursor-compatible `mcp.json` notation; see its [MCP server guide](https://lmstudio.ai/docs/app/mcp) for current setup details.