TTSim-MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TTSim-MCP roll the white dice and tell me what I got"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.

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" .-> MCPYou talk to Claude in Claude Code, e.g. "let's play backgammon". Claude loads the matching skill.
The skill tells Claude how this table works. Claude acts through the TTSim-MCP tools.
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:39999and replies tolocalhost:39998).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 |
| Is TTSim reachable, which game is loaded, who is seated |
| Run any Lua in the game and get the result back (the universal tool) |
| Read the game's scripts (read-only) and messages TTSim sent on its own |
| Objects on the table with position, rotation, tint, bounds, snap points |
| Move pieces smoothly and wait until they have settled |
| Table size, distances, point out a piece to the player |
| Roll dice (and flip coins) with TTSim's physics and read the results; flags dice that landed tilted |
Requirements
Tabletop Simulator running on the same machine, with a game loaded
Python 3.11 or newer
Developed and tested on macOS
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
Start Tabletop Simulator and load the built-in Backgammon game.
Open Claude Code in this folder and approve the
ttsimMCP server when asked.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 |
| Raw External Editor API connection: send Lua, receive results and events |
| Read-only access helpers and the generic 3D controls |
| The MCP server: thin layer exposing those functions as tools |
| All Lua the server sends to TTSim, as template files |
| The Backgammon skill ( |
| The Nine Men's Morris skill ( |
| Requirements, findings about TTSim behaviour, and the changelog |
| 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 toolsget_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, orguids+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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Teamfight Tactics data & AI coaching for Claude and ChatGPT — 19 tools, built-in Riot key.
One workspace of tools for Claude and ChatGPT: connect 600+ apps, generate media, build tools.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Ask Claude, ChatGPT, or any MCP client about your game's players, retention, revenue, and win rates.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to directly control Unity Editor, supporting scene manipulation, component operations, asset management, prefab handling, and audio control through natural language commands.5MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables Claude to design and build interactive 3D games within the Portals virtual platform through direct API integration. It facilitates automated asset placement, interaction logic configuration, and quest management using natural language commands.4-
- FlicenseNot gradedqualityDmaintenanceEnables controlling a game character, drawing on a canvas, and running chemistry experiments via natural language commands to Claude.-
- AlicenseNot gradedqualityCmaintenanceEnables Claude to drive a live GIANTS Editor 10.x (FS25) session with 59 tools for terrain editing, field creation, asset placement, map audits, and more through natural language.3MIT