AI Feedback Loop (MCP)

Set up the PyBevy MCP server so AI agents can see, edit, and iterate on your 3D scenes in real time.

Introduction

The PyBevy MCP server lets AI agents — Claude Code, Cursor, Codex, Gemini CLI — inspect and manipulate running Bevy scenes through the Model Context Protocol.

The AI can:

• Run and reload your scene with hot reload
• Take screenshots to see what it built
• Query entities and read component values
• Spawn, edit, and despawn entities live
• Check spatial relationships — distances, overlaps, bounding boxes

This creates a tight feedback loop: the AI writes code, sees the result, and iterates — all without you leaving your editor.

Setup

Claude Code

Using the CLI:

claude mcp add pybevy -- pybevy mcp

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "pybevy": {
      "command": "pybevy",
      "args": ["mcp"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pybevy": {
      "command": "pybevy",
      "args": ["mcp"]
    }
  }
}

Codex / Gemini CLI

codex mcp add pybevy -- pybevy mcp
gemini mcp add pybevy pybevy mcp

Virtual environments

If pybevy isn't on your PATH (e.g., installed via Poetry or in a venv), use the full path:

claude mcp add pybevy -- /path/to/virtualenv/bin/pybevy mcp

Auto-load a Scene on Startup

Pass a script path to start with a scene already running when the MCP server connects:

{
  "mcpServers": {
    "pybevy": {
      "command": "pybevy",
      "args": ["mcp", "my_scene.py"]
    }
  }
}

HTTP Transport

When you add McpPlugin() directly to your app, an HTTP+SSE server starts inside the Bevy process — no separate bridge needed.

Basic setup

By default it listens on http://127.0.0.1:8420/mcp/v1. Customize the port and host:

This is useful for connecting non-stdio MCP clients or custom tooling directly to a running scene.

The stdio setup (pybevy mcp) uses a separate Python bridge process that manages the Bevy app as a subprocess. The bridge sets PYBEVY_MCP_PIPE=1 internally, which switches McpPlugin to pipe transport instead of HTTP.

Customizing MCP Content

The MCP server serves contextual documentation to AI agents from the pybevy/mcp/ folder:

• instructions.md — Default instructions sent when the MCP server connects. Contains core API patterns, conventions, and usage guidance.
• guides/ — Topic-specific guides served on demand (lighting, camera, queries, performance, etc.).

Ejecting for customization

To override tool descriptions and prompts:

pybevy mcp-eject

This ejects to .pybevy/mcp/ and creates a pack.toml with all tool descriptions commented out for patching, plus editable Markdown prompt files. Uncomment and modify entries to override the defaults.

Troubleshooting

No window appears (Linux)

The Bevy subprocess needs access to the display server (X11 or Wayland). The bridge auto-detects display environment variables, but if that fails, pass them explicitly in .mcp.json:

{
  "mcpServers": {
    "pybevy": {
      "command": "pybevy",
      "args": ["mcp"],
      "env": {
        "DISPLAY": ":0",
        "WAYLAND_DISPLAY": "wayland-0",
        "XDG_RUNTIME_DIR": "/run/user/1000"
      }
    }
  }
}

Check your values with echo $DISPLAY $WAYLAND_DISPLAY $XDG_RUNTIME_DIR.

Subprocess crashes on startup

If run_scene returns an error with "subprocess crashed", check the error message — it includes stderr output. Common causes:

• Missing Python dependencies
• Scene file syntax errors
• GPU/driver issues (try pybevy watch <script> directly to diagnose)