About diceport
diceport is a CLI and MCP server for rolling dice, flipping coins, and choosing random integers. Optional seeds make outcomes reproducible, and dice rolls report each face as well as the total.
Key features
- 01Roll dice using NdM notation
- 02Flip a coin
- 03Generate an integer in a range
- 04Reproduce results with seeds
- 05Show individual dice faces and totals
Use cases
- 01Run seeded random choices in scripts
- 02Record dice faces for a game roll
MCP support
Its stdio MCP server exposes tools for dice rolls, coin flips, and inclusive-range random integers; each accepts an optional seed.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
3Saved tool list · updated 1d ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| seed | integer | No | Seed for a reproducible roll |
| notation | string | Yes | Dice notation such as 2d6 or 3d8+2 |
Details
From the project READMEdiceport
diceport rolls dice, flips coins, and picks random integers. It is built for the moments when a script or an agent needs a fair, explainable bit of chance: a roll reports every face that went into its total, and any call can take a seed that makes the outcome reproducible — same seed, same result, every time.
Install
npx @reneturcios/diceport roll 2d6
Or run the container image:
docker run -i ghcr.io/cloudcorprecords/diceport
The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead.
CLI
# Roll dice in NdM notation, with an optional +N / -N modifier
diceport roll 2d6
# 2d6: [3, 5] total 8
diceport roll 3d8+2 --seed 42 # reproducible
# Flip a coin
diceport flip # heads (or tails)
diceport flip --seed 7 --json
# Pick an integer between two bounds, inclusive
diceport random 1 100
diceport random 1 100 --seed 42
diceport --version
Notation is NdM: roll N dice with M sides each. The count may be
left off (d20 rolls one die) and a flat modifier may be appended
(2d6+3, 1d100-5).
Exit codes: 0 on success, 1 when a roll or range cannot be done
(bad notation, an inverted range — the error says why), 2 for usage
errors.
MCP server
One bin serves both faces. The mcp subcommand starts a stdio MCP
server:
npx -y @reneturcios/diceport mcp
MCP client configuration:
{
"mcpServers": {
"diceport": {
"command": "npx",
"args": ["-y", "@reneturcios/diceport", "mcp"]
}
}
}
Tools
| Tool | Input | What it returns |
|---|---|---|
roll_dice | notation (string, required, e.g. 2d6+3), seed (integer, optional) | Every individual face rolled, the modifier, and the total. |
flip_coin | seed (integer, optional) | heads or tails. |
random_number | min, max (integers, required), seed (integer, optional) | One integer between min and max, inclusive. |
Seeded calls use a mulberry32 generator, so a seed fully determines the outcome and any reported result can be replayed. Unseeded calls draw from the platform random source.
Development
npm install
npm run build # tsc -> dist/
npm test # node test runner over test/*.test.ts, no network
npm run dev # run the CLI from source via tsx
License
MIT — see LICENSE.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.