TTCraft MCP lets an AI assistant securely manage and inspect live TTCraft tables through your account.
Sign in/out via browser device code, check auth, and manage table connections.
List, connect, reconnect, disconnect, and inspect running tables and connection status.
Read cached table state, objects, events, and console logs.
Spawn, move, patch, lock/unlock, and remove objects.
Apply declarative table plans and idempotent blueprints for repeatable setups.
Search/describe/run native TTCraft commands, including dry-run batches.
Manage templates/library items and save/update templates.
Read, write, compile, and version-check Lua scripts; debug via console/events.
List/upload assets and import/export table archives/modules.
Create named table snapshots and search/read bundled TTCraft docs and command references.
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., "@TTCraft MCP Inspect my table and add a draw pile, discard area, and four player areas."
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.
🎲 Build a whole table. Create and arrange objects, work with cards and templates, define player areas, zones and snaps.
🤖 Use your preferred assistant. Claude Code, Codex, Cursor, VS Code and other clients that support local MCP servers.
🖥️ Watch it work. Keep the table open in your browser. MCP works alongside your player session without taking your seat or disconnecting the tab.
📜 Write and debug Lua. Let the assistant read scripts, edit local files, compile changes and inspect the console.
🎨 Bring your assets. Upload images, models, audio, fonts and PDFs for use in templates and objects.
🧩 Repeat a setup. Blueprints update tracked objects instead of making another copy of every piece.
💾 Keep a backup. Export a portable table archive before a large change, or add content from module archives.
📚 Give the agent the actual manual. The package includes TTCraft documentation and a searchable command reference.
Related MCP server: DesyncedMCP
Codex and Claude Desktop can connect without installing this package.
Add https://ttcraft.net/mcp as a remote Streamable HTTP connector and sign in
with your TTCraft account through OAuth. Codex CLI users can run:
codex mcp add ttcraft --url https://ttcraft.net/mcp
codex mcp login ttcraftIn Claude Desktop use Connectors → Add custom connector, enter the URL and
choose OAuth. Both published client identities and dynamic registration are
supported. Your existing table permissions apply, and access can be revoked in
TTCraft Settings → Security. Remote file tools use your private /workspace/;
files_write / files_read transfer bounded chunks. See
remote hosting for deployment and limits.
Give your assistant this message:
Set up TTCraft MCP using https://ttcraft.net/docs/mcp-setup.md . Install it on this computer and configure this client, preserving my existing MCP servers. Verify that the tools load, help me sign in through the browser, then list my running tables. Ask me which table to use before changing anything.
The assistant handles installation and configuration. You approve the TTCraft login in your browser and choose the table. Your client may need a restart to load the new tools. The complete guide explains each step.
You need Node.js 22 or newer, a TTCraft account and a client that can launch local MCP servers. Get Node.js LTS if needed. No VS Code extension or GitHub token is required.
npm install --global https://ttcraft.net/downloads/ttcraft-mcp-0.1.2.tgz
ttcraft-mcp setupCopy the Claude Code or Codex command printed by setup, run it and
reload MCP or restart the client. The commands contain the correct absolute
paths for your computer. For other clients, use the JSON configuration printed
by setup; VS Code's servers format is included in setup --json.
Running setup alone does not change settings.
On Windows, use npm.cmd and ttcraft-mcp.cmd if PowerShell blocks .ps1
launchers. If global installation needs administrator access, follow the
private-folder installation.
The release is served directly by TTCraft as a versioned archive; do not
substitute an unqualified npm registry package name.
Start the table from its room on ttcraft.net. You need Manage table permission; owners and moderators normally have it.
Ask your assistant to sign in. It gives you a TTCraft approval link and short code. Approve in the browser, then tell the assistant you are ready. Your password stays in the browser.
Choose your table from the list the assistant retrieves. It inspects the existing state before making changes.
Keep the browser tab open and describe what you want to build.
You can also use ttcraft-mcp login in a terminal. Reconnect an already-running
MCP server afterward so it reads the saved credential.
Inspect my table. Add a draw pile, a discard area and four player areas. Reuse existing pieces and show me the plan first.
Find why scoring does not update. Read the Global and dice scripts, fix them, compile and check the console.
Create a repeatable six-player setup. Dry-run it, apply it and verify that a second application does not duplicate pieces.
Export a backup to a ZIP before changing the layout.
The assistant has 37 tools and a reference for 144 native commands. Describe the result you want without learning tool names. Details are in tools and workflows, Lua scripting and table plans.
Changes affect the shared table. Export a backup before a large replacement. Archive import replaces the world; module import adds content.
Your permissions still apply. MCP follows your account permissions and table rules.
Tables must be running. Start them from the room page. Practice/tutorial tables are excluded.
Browser and agents coexist. Several agents can connect; coordinate edits to the same scripts or objects. Older instances need a saved restart onto a server with tool-session support. MCP refuses them before connecting.
Two transports. The hosted OAuth connector uses HTTPS; local filesystem workflows can use stdio. Over SSH or in a container, install the stdio package where the assistant runs.
Login can be revoked. Use TTCraft Settings → Security to revoke the device. ttcraft-mcp logout removes the local credential.
Problem | What to check |
Tools do not appear | Run the client command printed by |
Launcher not found | Reopen the terminal after installing Node. Use the absolute paths from |
Empty table list | Start the table and check Manage table permission. |
Signed out | Ask the assistant to start browser sign-in and wait for approval. |
Table needs an update | Save and restart it after the server upgrade. Do not bypass the compatibility check. |
Operation timed out | Reconnect and inspect the result before repeating a change. |
More help: full guide · report an issue.
Install the version listed in the guide again, then reload MCP. If the installation
path changed, rerun setup and update the client configuration.
To remove it, delete ttcraft from your client's MCP settings and run
npm uninstall --global ttcraft-mcp for a global installation. Revoke its device
in TTCraft settings if you also want to end account access.
See CONTRIBUTING.md for builds, tests and backend integration. Bug reports and ideas are welcome in Issues.
MIT © TTCraft.
Export the whole table and assets to an absolute local ZIP path. Useful as a backup before major edits. Streams to disk and refuses to overwrite unless requested.
Inputs: output_path (required), table_id, overwrite.
Load a local TTCraft ZIP archive into the shared table, REPLACING current objects. Requires Admin. Export a backup first. Reconnects after success. Never automatically retries the import.
Inputs: file_path (required), table_id.
Read/search the uploaded asset gallery (images, models, fonts, audio, PDFs) with pagination.
Inputs: limit, query, offset, table_id.
Upload a local image/model/model ZIP/font/audio/PDF to the table gallery. Uses bounded-memory chunked uploads. Returns a library/assets path to reference in templates and objects. Path must be absolute.
Inputs: file_path (required), name, table_id.
Start the same browser device-code sign-in as the VS Code extension. Opens a browser by default; disable on a headless host. Show the returned URL and code to the user, then call auth_poll after the indicated interval.
Inputs: open_browser.
Disconnect all tables and remove the local login. Revocation on the TTCraft website is separate.
Inputs: no named parameters.
Check browser approval once, respecting server polling intervals. Stores the token securely without exposing it to the model.
Inputs: no named parameters.
Check TTCraft login and identity. Never returns credentials.
Inputs: no named parameters.
Run up to 100 native commands sequentially without interleaving other MCP commands. Prevalidates names. dry_run defaults true; set false to apply. Not atomic; returns completed steps on failure, with no automatic replay.
Inputs: commands (required), dry_run, table_id, stop_on_error.
Build/update a complete table from a validated blueprint: plan, templates, tracked objects, poses, properties and scripts. Stable id/key mappings persist locally. Dry run first; set dry_run=false to apply. Reapplying updates GUIDs without duplicating existing objects. Does not delete omitted objects or provide atomic rollback. Templates are cloned into standalone objects.
Inputs: blueprint (required), dry_run, table_id.
Read exact native command fields, required capability and reference handler from the bundled server source snapshot. Fields are inferred hints; use docs and the handler for types/defaults. Native commands may return no acknowledgement.
Inputs: command (required), offset, max_characters.
Discover the native TTCraft command catalog by name/domain/field. Covers cards, containers, tablets, UI actions, effects, materials, lighting, music, zones, decals, players, undo and more. Call command_describe before using an unfamiliar command.
Inputs: limit, query, domain, offset.
Show active table, connections, protocol versions and granted capabilities.
Inputs: no named parameters.
Read bounded console logs, including compilation/runtime errors. Pass after_cursor from the previous call. wait_ms optionally waits for new logs up to 20 seconds.
Inputs: wait_ms, table_id, after_cursor.
Read a bundled TTCraft manual page with character pagination. Examples: table-plan, table-archives, scripting, scripting-world, scripting-objects, scripting-ui, scripting-events.
Inputs: slug (required), offset, max_characters.
Search bundled TTCraft manual and Lua API without internet/login. Empty query lists document slugs.
Inputs: query.
Read table event history with a cursor (up to 500 retained messages). Filter by message types. Reports truncation; state_read/objects_list are the authoritative current state.
Inputs: types, wait_ms, table_id, after_cursor.
Search library templates by name/category/id/kind. Includes scripts and large geometry only with details=true; script_read reads template scripts separately.
Inputs: limit, query, offset, details, +2 more.
Create a template or update an existing template by id, preserving omitted fields from the cached full template. Changes may affect linked instances. Locked built-ins cannot be overwritten.
Inputs: spec (required), id, table_id.
Additively merge one or more local TTCraft module ZIP archives. Supports per-package layout and optional table shape/global-script selection. Requires Admin. Reconnects after success.
Inputs: packages (required), table_id, table_shape_from, apply_global_script.
Read one object by stable GUID or runtime id. refresh asks the server for current properties. Returns paginated JSON text.
Inputs: object (required), offset, refresh, table_id, +1 more.
Find objects by name, kind, GUID or id, including live positions and rotations. Paginated. details includes full properties.
Inputs: limit, query, offset, details, +1 more.
Lock or unlock a list of objects.
Inputs: locked (required), objects (required), table_id.
Place an object in metres with optional quaternion rotation [x,y,z,w] and scale [x,y,z]. Locked objects must be explicitly unlocked with objects_lock first. Inspect state afterwards to verify clamping/physics.
Inputs: object (required), scale, position, rotation, +1 more.
Patch appearance/physics/name properties on one or more objects. Properties follow setprops; use command_describe for exact fields. label is the display name.
Inputs: objects (required), properties (required), table_id.
Remove objects from the live shared table. Cascade rules include attached contents. Export a backup first when needed.
Inputs: objects (required), table_id.
Spawn an object or a native linked library template. For a template, spawn fields come from the template; use objects_patch afterwards. Returns observed new objects, which can also include concurrent spawns by others. Use blueprint_apply for reliably tracked repeated builds.
Inputs: position (required), spec, table_id, template.
Read a Global, object or template Lua script with SHA-256 for conflict detection. Page large source or write to an absolute output_path for local editing. Existing files are never overwritten.
Inputs: object, offset, target, table_id, +3 more.
Compile and install Lua source on the live table. Supply exactly one of code/file_path. expected_sha256 checks the current source before writing. A compile failure returns isError and the previous script stays active. Read console afterwards.
Inputs: code, object, target, table_id, +3 more.
Read a cached authoritative state section (table, zones, snaps, drawings, decals, players, groups, timemachine, policy, lighting, music, etc.). Omit section for a compact overview. Large sections are paged as JSON text.
Inputs: offset, section, table_id, max_characters.
Run a native TTCraft command from the catalog. Read command_describe first. Supply protocol fields in arguments; object id must be a current runtime id. Server enforces all permissions and script vetoes. processed_unverified is not a success acknowledgement.
Inputs: command (required), table_id, arguments, timeout_ms, +1 more.
Connect to a running table and make it active. Supports multiple connected tables; pass table_id on later calls to select explicitly.
Inputs: table_id (required).
Disconnect this MCP client from a table. Does not shut down the shared table.
Inputs: table_id.
Apply the TTCraft declarative table plan: shape, seats, areas, snaps. Read table-plan docs first. Returns server validation errors/warnings. merge patches the stored plan.
Inputs: plan (required), merge, table_id.
Reconnect and get a fresh full state after connection loss. Does not replay commands.
Inputs: table_id (required).
Create a named snapshot in the table server database (native savetable). This is separate from TTCraft account save slots. Use archives_export for a portable backup.
Inputs: name (required), table_id.
List TTCraft tables that your account can manage, with running status, room and channel.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 37 tools
Most tools have clear resource/action targets, but several clusters overlap: table_command vs. batch_execute, commands_search vs. command_describe, and objects_spawn vs. blueprint_apply vs. table_plan_apply. The descriptions help distinguish intent, but an agent can still misselect among creation and command-execution paths.
The set largely follows a predictable resource_action pattern (docs_search, objects_list, script_read, archive_export-style). Minor inconsistencies exist, such as singular/plural mixes (object_read vs. objects_list, asset_upload vs. assets_list) and a few noun_status or noun_noun names like connections_status and table_command.
37 tools is heavy for most MCP servers, though this server covers a broad domain spanning auth, tables, objects, scripts, assets, archives, blueprints, and native commands. Each tool is reasonably purposeful, but the surface is at the borderline of being too large and could benefit from consolidation.
The surface is broad and covers core workflows well: docs, auth, table lifecycle, object CRUD, scripting, console/events, commands, blueprints, assets, archives, and snapshots. Minor gaps remain, such as no delete operations for library templates or uploaded assets, and no table creation operation, but most agents can work around these.
Files and tables your AI reads and writes from any chat, with version history and sharing.
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
Play and build AI RPG worlds: your agent tells the story, Worldtable keeps HP, items and the map.
Build, edit and preview browser games and web apps in your Amplify account from your AI agent.