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" .-> 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

Requirements

• Tabletop Simulator running on the same machine, with a game loaded

• Claude Code

• 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

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

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.