sims4-tc-mcp

Disclaimer: This is a vibecoded project

A Model Context Protocol server for building, inspecting, packaging and debugging script mods (.ts4script) and total conversions for The Sims 4.

Point any MCP-capable agent (OpenCode, Claude Desktop, Cursor, …) at it and it can hash resources, read/write .package files, search vanilla tuning, validate Python 3.7 for the game's interpreter, patch catalog flags, package .ts4script zips, and parse lastException tracebacks.

Built on the official mcp Python SDK, lxml, pydantic v2 and SQLite FTS5.

Features

Related MCP server: paradox-toolkit

Requirements

• Python 3.11+ (the package pins 3.12 through uv)

• uv

• Linux or macOS; the stdio server also runs on Windows, the auto-setup helpers are POSIX-oriented (systemd/desktop launcher)

Install

git clone https://github.com/SomeoneToldJotaroDolphins-AreGood/sims4-tc-mcp.git
cd sims4-tc-mcp
uv sync

Run the test suite (107 tests):

uv run pytest

One-click setup

sims4-tc-mcp-setup finds your game folder, creates a bearer token, writes a config file, and starts the server — no environment variables needed:

uv run sims4-tc-mcp-setup --tui      # interactive menu (recommended)
uv run sims4-tc-mcp-setup --auto     # zero questions, background service
uv run sims4-tc-mcp-setup --status   # what was detected / is it running?
uv run sims4-tc-mcp-setup --launcher # add a desktop icon that opens the TUI

The TUI shows detected paths, lets you start the server in the foreground or as a systemd user service, change the port, and print a ready-to-paste client config.

Auto-detected game folders:

It also picks up ~/sims4/extracted/tuning, ~/sims4/extracted/tdesc and ~/sims4/decompiled when they exist. Anything missing can be overridden with --user-dir/--mods-dir/--tuning-dir/--tdesc-dir/--scripts-dir.

Settings live in ~/.config/sims4-tc-mcp/config.json (mode 0600) with the token in ~/.config/sims4-tc-mcp/token. Environment variables still take precedence, so containers and CI keep working.

Manual run

stdio (the default; what desktop MCP clients spawn):

uv run sims4-tc-mcp

Nothing is printed — stdio is a silent JSON-RPC pipe. To poke at it:

uv run mcp dev src/sims4_mcp/server.py

HTTP (for remote clients):

SIMS4_MCP_TRANSPORT=streamable-http \
SIMS4_MCP_HOST=0.0.0.0 \
SIMS4_MCP_PORT=7348 \
SIMS4_MCP_AUTH_TOKEN="$(openssl rand -hex 24)" \
uv run sims4-tc-mcp

Binding any non-loopback interface without SIMS4_MCP_AUTH_TOKEN refuses to start. Loopback binds may run token-less.

Configuration

All paths are optional. Without game files the server still works; tools that need an index report unconfigured with a hint instead of failing.

Build the indexes once the data is available:

// tools: rebuild_indexes(tuning=true, python_api=true, tdesc=true, force=false)

Remote use (game PC → laptop)

Run the server where the game and its files live, connect from anywhere on the LAN:

# on the game machine
uv run sims4-tc-mcp-setup --tui     # option 2 installs + starts the service

Then open the port on that machine (Fedora example):

sudo firewall-cmd --add-port=7348/tcp --permanent && sudo firewall-cmd --reload

The token is plain HTTP on the LAN; use an SSH tunnel if you cross untrusted networks:

ssh -L 7348:127.0.0.1:7348 user@game-pc

OpenCode configuration

opencode.jsonc (project root or ~/.config/opencode/opencode.jsonc). Servers go under mcp.servers:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      // local stdio variant (server on the same machine)
      "sims4-tc-mcp": {
        "type": "local",
        "command": ["uv", "run", "--directory", "/path/to/sims4-tc-mcp", "sims4-tc-mcp"],
        "environment": {
          "SIMS4_USER_DIR": "~/Documents/Electronic Arts/The Sims 4",
          "SIMS4_MODS_DIR": "~/Documents/Electronic Arts/The Sims 4/Mods"
        }
      },
      // remote variant (server on the game PC)
      "sims4-tc-mcp-remote": {
        "type": "remote",
        "url": "http://192.168.1.50:7348/mcp",
        "headers": { "Authorization": "Bearer <token>" },
        "timeout": { "startup": 15000 }
      }
    }
  }
}

uv run sims4-tc-mcp-setup --print-client-config prints exactly this block with your detected address and token filled in.

Tools

Resources: sims4://config, sims4://indexes. Prompt: total_conversion_workflow.

Project layout

project/
  tuning/*.xml          # tuning documents (i:id or s=/n=)
  *.stbl.json           # {"base_name": "...", "locales": {...}}
  bin/*.bin + *.tgi     # raw binary resources with TGI sidecars

build_package("/path/MyMod.package", "/path/project")

Notes & limitations

• SimData format is community RE'd and table-specific; the codec is generic and round-trip safe, while XML auto-compilation supports the registry in simdata/compilers.py (extend with register()).

• .pyc files: only 16-byte CPython 3.7 headers (magic 3394) can be produced on a newer host. .ts4script ships .py source, which the game compiles itself — that is the supported path.

• Catalog flags: CASP AllowForRandom uses the officially documented partFlags bit 2. COBJ flag-word semantics are partially undocumented; the patcher exposes configurable word/bit targets (CASP conventions by default) and preserves every other byte.

• Live bridge binds loopback only and requires a shared token; exec is disabled unless explicitly allowed on both sides.

Development

uv sync
uv run pytest -q              # 107 tests
uv run pytest -v tests/test_dbpf.py

Coverage: FNV known answers, DBPF round-trips across flag combinations, STBL v5 + 18 locales, SimData codec + compilers, tuning FTS + graph, gatekeeper matrices, pyc headers, injector templates, packager, CASP/COBJ/OBJD patching, HTTP transport + bearer auth, setup detection, and every MCP tool (in-process client included).

Security

The HTTP transport exposes file-reading and file-writing tools. It requires a bearer token for every request and refuses to bind a non-loopback interface without one. Never commit the token (.gitignore covers the common names).

Please report vulnerabilities privately — see SECURITY.md.

License

MIT — see LICENSE.

Disclaimer

Not affiliated with or endorsed by Electronic Arts, Maxis, or Mod The Sims. The Sims is a trademark of Electronic Arts Inc. This project ships no game assets; you need your own legally installed copy of the game.