spz-mcp

An MCP server that lets an LLM agent drive StableProjectorz — inspect the loaded 3D model, read the app's state, look at the viewport, and trigger UI actions.

It talks to the agent bridge built into the app: a loopback-only JSON socket.

Claude Code / Claude Desktop  ──MCP(stdio)──►  spz-mcp  ──TCP 127.0.0.1:8765──►  StableProjectorz

The server knows nothing about StableProjectorz

On every tools/list, it asks the running app for its catalogue via the bridge's describe command and republishes it as MCP tools, building each JSON Schema from the parameter descriptions the app supplies.

Nothing is hard-coded here. Adding a tool to the app does not require a new release of this server — which is exactly what allows the app and this server to live in separate repositories without drifting apart.

Related MCP server: BlenderMCP

Setup

1. Enable the bridge in StableProjectorz

Add this to spz.config, next to the executable (or at the project root when running from the Unity Editor), then restart the app:

--agent-bridge

Optional:

--agent-bridge-port=8765
--agent-bridge-token=some-secret   # pins your own secret; normally unnecessary

The Unity console should log [SPZ_Agent_Bridge] listening on 127.0.0.1:8765.

About the token. The bridge requires one on every request. If you don't pin one, the app generates a secret on first launch and writes it to %LOCALAPPDATA%/StableProjectorz/agent-bridge.token (~/.local/share/... elsewhere). This server reads that same file, so there is nothing to configure — and because it re-reads until it finds one, starting this server before the app is fine.

2. Register the server

Claude Code:

claude mcp add spz -- uvx --from git+https://github.com/redDwarf03/spz-mcp spz-mcp

Claude Desktop — in claude_desktop_config.json:

{
  "mcpServers": {
    "spz": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/redDwarf03/spz-mcp", "spz-mcp"]
    }
  }
}

For a non-default port, add "env": {"SPZ_PORT": "8765"}. The token is picked up automatically.

From a local checkout

pip install -e ".[dev]"
spz-mcp --port 8765

Tools

The list comes from the app at runtime. With the current bridge you get:

Plus one tool this server adds itself:

spz_bridge_status is also the only tool published while the app is down, so an agent can diagnose the situation instead of finding an unexplained empty toolbox.

Options

Protocol

One JSON object per line over TCP:

->  {"id":"1","tool":"get_app_state","params":{}}
<-  {"id":"1","ok":true,"result":{"app_version":"2.4.5","sd_connected":true, ...}}
<-  {"id":"1","ok":false,"error":"unknown tool 'foo'. Call 'describe' for the catalogue."}

The app serves one request at a time per connection, so this client serialises calls behind a lock rather than multiplexing on id.

Notes and limits

• The bridge is opt-in and loopback-only, but it is an unauthenticated local control channel unless you set a token. Any process on the machine can connect. Enable it only while you are using it.

• Screenshots wait on an async GPU readback, so they can take a moment; overlapping captures are rejected rather than left hanging.

• Managers in the app live in additively-loaded scenes, so calls made during startup may report that a subsystem is not ready yet.

Tests

pip install -e ".[dev]"
pytest

The suite runs a fake bridge over a real TCP socket, so the client is exercised end to end without needing StableProjectorz running. Each test has a 30 s timeout: these all talk to a local socket and finish in milliseconds, so a hang is a bug and should fail rather than block the suite.

Linting and formatting use ruff:

ruff check .
ruff format .

CI/CD

ci.yml runs on every push to main and every pull request:

• lint — ruff check and ruff format --check

• test — Python 3.10 through 3.14 on Linux, plus one Windows leg (the app this server drives is Windows-first)

• build — builds the wheel and sdist and validates the metadata with twine check

release.yml runs on a v* tag. It refuses to proceed if the tag does not match the version in pyproject.toml, then builds and attaches the distributions to a GitHub release with generated notes.

Publishing to PyPI is off by default, since the server installs fine straight from git. To enable it:

1. claim the spz-mcp name on PyPI

2. add a trusted publisher for this repo, workflow release.yml, environment pypi

3. set the repository variable PUBLISH_TO_PYPI to true

No token is stored anywhere — publishing authenticates over OIDC.

License

MIT — see LICENSE.

The StableProjectorz app itself is AGPL-3.0. This server is a separate program that communicates with it over a socket, and is deliberately kept in its own repository so it can be reused and relicensed independently.