Installing the Godot & PixelLab MCPs

Module 8 · Lesson 2 · ~30 min · one-time setup

MCP (Model Context Protocol) is an open standard for letting LLMs like Claude call external tools. For game dev you care about two: a Godot MCP (editor + runtime control) and PixelLab MCP (pixel art generation). Install once — then they're always available when you run Claude Code in this project.

Where MCPs live Claude Code reads MCP configuration from .mcp.json (project-local, shared via git) or from a user-level config (claude mcp add on the command line). For a curriculum project like this, project-local .mcp.json is the cleanest — it makes the setup reproducible on any machine.

1. The Godot MCP

The most mature community Godot MCP as of 2026 is Coding-Solo/godot-mcp on GitHub. It exposes a set of tools Claude can invoke:

launch_editor — open Godot on a project
run_project — start the game and capture output
get_debug_output — read stdout/stderr from the running game
stop_project — stop the running game
get_project_info — read godot version, main scene, project root
list_project_files — enumerate .tscn, .gd, .tres in the project
get_godot_version, create_scene, add_node, save_scene — editor scripting

Install

# In your project root
git clone https://github.com/Coding-Solo/godot-mcp.git .mcp-servers/godot-mcp
cd .mcp-servers/godot-mcp
npm install
npm run build

(Check the repo's README — installation details evolve. The project's current README is authoritative.)

Configure

Create .mcp.json at your project root:

{
  "mcpServers": {
    "godot": {
      "command": "node",
      "args": ["./.mcp-servers/godot-mcp/build/index.js"],
      "env": {
        "GODOT_PATH": "/Applications/Godot.app/Contents/MacOS/Godot"
      }
    }
  }
}

Key points:

GODOT_PATH must be the actual binary, not the .app bundle. On macOS it's inside the bundle as above.
Path is relative to your project root — Claude Code resolves it from where you launched.
Gitignore .mcp-servers/ if you don't want to commit the server source.

2. The PixelLab MCP

PixelLab (pixellab.ai) is a service that generates pixel art from text prompts — sprites, tilesets, animations. It publishes an official MCP server that plugs into Claude Code.

Install

git clone https://github.com/pixellab-ai/pixellab-mcp.git .mcp-servers/pixellab-mcp
cd .mcp-servers/pixellab-mcp
npm install
npm run build

Get an API key

Sign up at pixellab.ai. Grab an API key from your dashboard. PixelLab has free tier credits that are enough to experiment — past that it's usage-based (roughly a few cents per generated asset).

Configure

Add to the same .mcp.json:

{
  "mcpServers": {
    "godot": { ... as above ... },
    "pixellab": {
      "command": "node",
      "args": ["./.mcp-servers/pixellab-mcp/build/index.js"],
      "env": {
        "PIXELLAB_API_KEY": "pk_live_xxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Never commit your API key. Options:

Gitignore .mcp.json and maintain a .mcp.json.example with placeholder values
Or put secrets in a separate .env, reference via shell expansion at launch time

3. Verify

In your project directory, start Claude Code:

claude

Then ask: "What MCP tools are available?" Claude should list the godot and pixellab tools. If not:

Check .mcp.json is at the project root (not a subdirectory)
Check the node script actually builds (ls .mcp-servers/godot-mcp/build/index.js)
Check Claude Code version — older versions used a different config format
Try claude mcp list to see recognized servers

4. Write a CLAUDE.md

This is the single biggest lever for consistent output. Create CLAUDE.md at your project root. It's automatically loaded every time you invoke Claude in this directory. Mine looks like:

# Lexicon Duel — Project Context

## Stack
- Godot 4.3 (stable)
- Target: Android first, then iOS
- Orientation: portrait

## Conventions
- Use **typed GDScript** always. `var x: int = 5`, not `var x = 5`.
- Snake_case for files and functions. PascalCase for classes.
- Scenes in `scenes/`, scripts in `scripts/`, data in `data/`, resources in `resources/`.
- Autoloads: `Global`, `Events`, `SFX`, `SceneTransition`.
- All signals are defined in `Events.gd` or on the emitting node. No ad-hoc bus.
- Resources over hardcoded data: card effects, enemy strategies, status effects all extend a typed base Resource.

## Patterns I use
- State machine lives in `DuelController`, enum-based.
- Turn actions go through `ActionQueue`.
- Combatant base class handles damage pipeline (Strength → Weakness → Block).

## Patterns I don't want
- Don't use `get_node("../../..")` — use @export references or signals.
- Don't use untyped Dictionary for card data — extend `CardData` Resource.
- Don't create new autoloads without asking — four is enough.

## When in doubt
- Ask before making architectural changes.
- Add a short comment only when the WHY is non-obvious.
- If you can delete code instead of adding, prefer deleting.

This file is conversation context, not code. Keep it under 200 lines. Rewrite when your mental model shifts.

5. The first vibe-coding session

Try this prompt in a fresh Claude session, inside your project directory:

"Run the project. Tell me what happens. If there are errors,
diagnose and propose a fix but don't edit yet."

Claude should use the Godot MCP's run_project, read the output via get_debug_output, and give you a diagnosis. No edits, just a readout. You're verifying the wire is live.

Then:

"Generate a pixel art portrait of a goblin wordsmith —
small, green, holding a scroll, 64x64 pixel art, top-down
view. Use PixelLab. Save to res://assets/enemies/goblin.png."

Claude uses the PixelLab MCP's generation endpoint, downloads the result, saves it. Usually ~20 seconds.

Common issues

"Godot process timed out." Your GODOT_PATH is wrong, or the binary isn't executable. Test manually: /Applications/Godot.app/Contents/MacOS/Godot --version.
"PixelLab auth failed." API key not set, or copied with a stray newline. Log into pixellab.ai, rotate the key, paste carefully.
Claude "forgets" the MCP is there. Start a fresh session. MCP tools appear at session start — if you edited .mcp.json mid-session, Claude won't see the new tools until you restart.
MCP server crashes on boot. Look at stderr in the Claude Code MCP logs (it surfaces them). Usually a missing env var or a Node version mismatch (needs Node 18+).

Do this now

Install both MCPs. Commit the .mcp.json.example (with redacted key) to your project.
Write your project's CLAUDE.md — use my template above, adapt to your conventions.
Test both MCPs with the two prompts above.
Save the goblin portrait and wire it into your enemy scene. First AI-generated asset in your game!