Skip to main content
Glama

Claude-TTSim-MCPServer

Let Claude play board games against you in Tabletop Simulator (TTSim). Claude reads the table, rolls real physics dice and moves its own pieces, and you watch it all happen in the game.

Claude playing Backgammon against Peter in Tabletop Simulator

Left: the conversation with Claude. Right: the same game in Tabletop Simulator, where Claude moves the light checkers.

How it works

Two parts work together:

  • TTSim-MCP is an MCP server that gives Claude generic access to Tabletop Simulator: run Lua in the game, list and inspect objects, move them, measure distances, roll and read dice. It knows nothing about any specific game.

  • Game skills teach Claude one game on one table: where the pieces are, how the board is laid out, the rules, and how a turn with you works. Skills so far: ttsim-backgammon (the built-in Backgammon table) and ttsim-nine-mens-morris (the Steam Workshop mod "Nine Men's Morris").

flowchart LR
    Claude["Claude<br/>(Claude Code)"]
    Skill["Claude Skill<br/>ttsim-backgammon<br/>rules · board layout · turn flow"]
    MCP["TTSim-MCP<br/>MCP server (Python)<br/>run_lua · objects · moves · dice"]
    TTSim["Tabletop Simulator<br/>External Editor API<br/>localhost:39999 / 39998"]
    Game["Loaded game<br/>Backgammon board,<br/>checkers, dice"]

    Claude -- "loads the skill<br/>for the game" --> Skill
    Skill -- "MCP tool calls<br/>(stdio)" --> MCP
    MCP -- "Lua as JSON" --> TTSim
    TTSim -- "runs Lua,<br/>physics" --> Game
    TTSim -. "results, events" .-> MCP
  1. You talk to Claude in Claude Code, e.g. "let's play backgammon". Claude loads the matching skill.

  2. The skill tells Claude how this table works. Claude acts through the TTSim-MCP tools.

  3. TTSim-MCP turns each tool call into Lua and sends it to Tabletop Simulator's External Editor API (the same interface script editors use; TTSim listens on localhost:39999 and replies to localhost:39998).

  4. TTSim runs the Lua in the loaded game: pieces glide to their new places, dice are thrown by the physics engine, and the results come back to Claude.

Dice are real: every roll is a visible physics roll in TTSim, never a number Claude makes up. A test of 400 rolls came out consistent with fair dice (see docs/requirements.md, Q8).

Related MCP server: Portals MCP

MCP tools

Tool

What it does

ttsim_status

Is TTSim reachable, which game is loaded, who is seated

run_lua

Run any Lua in the game and get the result back (the universal tool)

get_scripts, get_events

Read the game's scripts (read-only) and messages TTSim sent on its own

list_objects, inspect_object

Objects on the table with position, rotation, tint, bounds, snap points

move_object, move_objects

Move pieces smoothly and wait until they have settled

table_geometry, measure, highlight

Table size, distances, point out a piece to the player

roll_dice, read_dice

Roll dice (and flip coins) with TTSim's physics and read the results; flags dice that landed tilted

Requirements

Setup

git clone https://github.com/PeterPeet/Claude-TTSim-MCPServer.git
cd Claude-TTSim-MCPServer
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

.mcp.json registers the server for Claude Code. It contains an absolute path to the Python in .venv. Change it to your own folder:

{
  "mcpServers": {
    "ttsim": {
      "command": "/path/to/Claude-TTSim-MCPServer/.venv/bin/python",
      "args": ["-m", "ttsim_mcp"]
    }
  }
}

The game skills are linked into .claude/skills/, so Claude Code finds them automatically in this folder.

Play

  1. Start Tabletop Simulator and load the built-in Backgammon game.

  2. Open Claude Code in this folder and approve the ttsim MCP server when asked.

  3. Say "let's play backgammon".

Claude plays the light checkers and rolls the white dice beside the board. You play brown with the blue dice: roll, move, and tell Claude when you are done. Claude reads your dice and move from the table, checks the move, and takes its turn.

The skill is written for the built-in Backgammon table that comes with Tabletop Simulator (one board with 120 snap points, light and brown checkers, white and blue dice). A Workshop backgammon mod may need small changes in skills/ttsim-backgammon.

Project layout

Path

Contents

ttsim_mcp/comms.py

Raw External Editor API connection: send Lua, receive results and events

ttsim_mcp/access.py, ttsim_mcp/table.py

Read-only access helpers and the generic 3D controls

ttsim_mcp/server.py

The MCP server: thin layer exposing those functions as tools

ttsim_mcp/lua/

All Lua the server sends to TTSim, as template files

skills/ttsim-backgammon/

The Backgammon skill (SKILL.md) and its Lua board helper (bg.lua)

skills/ttsim-nine-mens-morris/

The Nine Men's Morris skill (SKILL.md) and its Lua board helper (nmm.lua)

docs/requirements.md

Requirements, findings about TTSim behaviour, and the changelog

tests/

Unit, contract (against a fake TTSim) and integration tests (against the real game)

Development

The project is requirements-driven: every feature has a requirement ID in docs/requirements.md and tests that reference it. See CLAUDE.md for the working method and architecture rules.

.venv/bin/pytest            # unit + contract tests, no TTSim needed
.venv/bin/pytest -m ttsim   # integration tests against the running game
.venv/bin/ruff check . && .venv/bin/ruff format --check .

Only one program can receive TTSim's replies at a time. While a Claude Code session is running the ttsim server, pytest -m ttsim fails with a "port in use" error; run the integration tests outside such a session.

Some integration tests show messages in the TTSim chat on purpose (a print, and a labelled deliberate syntax error).

Roadmap

  • Access to TTSim through the External Editor API

  • MCP server with raw access tools

  • 3D controls and physics dice

  • Backgammon: Claude plays against you (v0.1.0)

  • Nine Men's Morris: coin toss, placing, moving, flying, mills (in progress)

  • Warhammer Age of Sigmar (Spearhead), using the mod's own dice area

License

GNU General Public License v3.0, see LICENSE.

Disclaimer

An independent hobby project, not affiliated with Berserk Games (Tabletop Simulator) or Anthropic.

Available Tools

13 tools
get_eventsA

Messages TTSim sent on its own since sequence number since: print output, Lua errors, game loaded/saved, objects created.

Returns {"events": [{"seq", "time", "kind", ...}], "last_seq"}. Pass last_seq as since next time to get only new events. Only events received while this server runs are available.

Inputs: since.

get_scriptsA

Read the loaded game's Lua scripts and UI XML (read-only).

Returns {"global": {"script", "ui"}, "objects": [{"guid", "name", "type", "script", "ui"}]}, listing only objects whose script or UI is not empty.

Inputs: no named parameters.

highlightB

Highlight an object for a few seconds to point it out to the player. color is a TTSim colour name: White, Red, Orange, Yellow, Green, Blue, Purple, Pink, ...

Inputs: guid (required), color, seconds.

inspect_objectA

Full details of one object: everything list_objects gives, plus scale, bounds (world-axis box: center, size), value (dice etc.), whether it is held or moving, and its snap points in world coordinates (e.g. the slots on a game board).

Inputs: guid (required).

list_objectsA

List objects on the table: guid, name, description, type, tags, tint (hex), position, rotation, locked, resting. Optional filters: name (case-insensitive substring), type (e.g. "Dice"), tag, tint (hex, e.g. "bbbbbb"). GUIDs change when a game is loaded, so look objects up each session.

Inputs: tag, name, tint, type.

measureB

Horizontal distance between two objects (GUIDs) or points ([x, y, z]), in world units. Returns center (centre to centre), edge (between bounding boxes, 0 if overlapping), dx, dy, dz.

Inputs: a (required), b (required).

move_objectA

Move one object to position (optionally rotation) and wait until it has settled. smooth=true (default) glides it so the player sees the move; false teleports it. Place pieces slightly above their resting height and let physics settle them. Returns the final position and rotation.

Inputs: guid (required), position (required), smooth, rotation.

move_objectsA

Move several objects at once and wait until all have settled. Either:

  • moves: [{"guid", "position", "rotation"?}, ...] for explicit targets, or

  • guids + offset [dx, dy, dz] to shift them together, keeping their formation.

Inputs: guids, moves, offset, smooth.

read_diceA

Read dice values without rolling (e.g. after the player rolled): the given dice/coins, or all dice and coins on the table. Coins report their face name, e.g. "Heads". Each die has value, resting, tilt, cocked, tint and position.

Inputs: guids, cocked_tilt.

roll_diceA

Roll dice with TTSim's physics roll (visibly lifted and spun, like pressing R) and wait until all have come to rest. Coins (and other objects with named faces) are flipped with TTSim's randomize and report their face name, e.g. "Heads"; only numeric dice count towards the total. Returns each die's value and tilt (degrees from lying flat), the total, and cocked: dice tilted more than cocked_tilt (default 10°, for flat surfaces), whose value may be disputed. Dice bounce: roll them where nothing else can be hit, e.g. in a dice tray.

Inputs: guids (required), cocked_tilt.

run_luaA

Execute Lua in the TTSim Global script context and return the result.

Use return to get a value back. Tables arrive as JSON objects/arrays; numbers, strings, booleans and nil (null) work too. TTSim objects (userdata) cannot be returned directly: return their fields instead, e.g. local o = getObjectFromGUID("abc123") return {name = o.getName(), pos = o.getPosition()}. Lua runtime and syntax errors come back as tool errors with the TTSim message. Changes made here are visible to the player immediately, so act deliberately.

Inputs: code (required).

table_geometryA

The table's type and bounding box (center, size), and global snap points. Snap points that belong to a board are listed by inspect_object on the board.

Inputs: no named parameters.

ttsim_statusA

Check whether TTSim is reachable; if so, return the loaded game's name, object count and seated players (colour, host). Never fails: an unreachable TTSim is reported, not raised.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a clearly distinct action or resource: script reading vs. Lua execution, single- vs. multi-object movement, rolling vs. reading dice, measuring vs. geometry, listing vs. inspecting objects. The singular/plural move_object/move_objects and roll_dice/read_dice pairs are explicitly differentiated in their descriptions, leaving no realistic ambiguity.

    Naming Consistency4/5

    The set is consistently snake_case and mostly follows a verb_noun pattern (get_scripts, list_objects, inspect_object, move_object, roll_dice, read_dice). A few tools deviate: ttsim_status and table_geometry are noun phrases while measure and highlight are bare verbs without an object, but these are still readable and predictable.

    Tool Count5/5

    13 tools is well within the ideal 3-15 range and each earns its place, covering distinct facets of tabletop simulation control (scripting, object manipulation, measurement, dice, status). No tool feels redundant or padded.

    Completeness4/5

    The surface covers the core lifecycle: reading scripts, executing arbitrary Lua, listing/inspecting objects, moving single/multiple objects, geometry, measurement, highlighting, and dice roll/read. Gaps exist around object creation/deletion, chat/player messaging, and save/load operations, but run_lua serves as a powerful escape hatch for most of these.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers