# renpy-mcp

An [MCP](https://modelcontextprotocol.io) server that lets editor assistants (Claude Code, Cursor, Copilot, Codex, Zed, and anything else that speaks MCP) work on a Ren'Py project through the Ren'Py SDK's command line, instead of guessing at `renpy.sh` invocations.

Every tool is a thin wrapper over a command the SDK already has. Nothing here reimplements the engine.

Background: [renpy/renpy#7313](https://github.com/renpy/renpy/issues/7313).

## Tools

| Tool | What it runs | What you get back |
|---|---|---|
| `renpy_lint` | `lint` | Problems as `{file, line, message}`, notes, statistics. Uses `lint --format json` on SDKs that have it ([#7314](https://github.com/renpy/renpy/pull/7314)) and parses the text report on older ones, so the shape is the same either way. |
| `renpy_project_info` | `quit --json-dump` | Labels, screens, transforms, and defines with file and line; name, version, resolution; the label flow graph where the SDK exports it ([#7318](https://github.com/renpy/renpy/pull/7318)). |
| `renpy_flow` | `quit --json-dump` | The flow for one label: jumps, calls, menus and their choices, fall-through, plus which labels reach it. |
| `renpy_compile` | `compile` | Parse errors as `{file, line, message}`. |
| `renpy_run_tests` | `test [filters]` | Pass/fail status, the `[rpytest]` summary, failures, output tail. Opens a window. |
| `renpy_last_traceback` | reads files | `traceback.txt`, `errors.txt`, and `log.txt` from the project. |
| `renpy_run_command` | anything | Runs any CLI command (`translate french`, `add_ids --dry-run`, `dialogue`, ...) and returns its output. |
| `renpy_version` | `--version` | Which SDK is in use. |

## Setup

You need a Ren'Py SDK (8.x) unpacked somewhere, and Python 3.10+.

```
uv tool install renpy-mcp        # or: pipx install renpy-mcp
renpy-mcp --check                # confirms which SDK it found
```

The SDK is found from `--sdk`, then the `RENPY_SDK` environment variable, then a search of the usual places (your home directory, Downloads, `/opt`, `/Applications`, `C:\`). If `--check` finds the wrong one, set `RENPY_SDK`.

### Claude Code

```
claude mcp add renpy -- renpy-mcp --sdk /path/to/renpy-8.5.3-sdk
```

### Cursor / VS Code / others

Add a stdio server entry:

```json
{
  "mcpServers": {
    "renpy": {
      "command": "renpy-mcp",
      "args": ["--sdk", "/path/to/renpy-8.5.3-sdk"]
    }
  }
}
```

### From a checkout

```
uv run renpy-mcp --sdk /path/to/sdk --check
uv run pytest                                     # parser tests
RENPY_SDK=/path/to/sdk uv run pytest              # plus the tests that drive the real SDK
```

## Notes

- Paths passed as `project` are the project's base directory (the one with `game` in it). Pointing at `game` itself also works.
- `renpy_run_tests` and anything that starts the game need a display. Everything else runs with dummy video and audio drivers, which the SDK does on its own for those commands.
- Output is capped at 20,000 characters per field; the head is dropped, not the tail, since that's where the error usually is.
- The SDK's CLI isn't a stable interface, and neither is this. The tools track the CLI documentation for the current release.

## License

MIT.