capybara-mcp

MCP server for Capybara game asset generation. Works with Claude Code, Cursor, Codex, OpenCode, Pi, and any MCP-capable agent.

Tools

| Tool | Description | |------|-------------| | generate_assets | Generate maps, characters, props, HUD, and audio | | get_job_status | Recover results if a session was interrupted |

Quick start

1. Configure (one time)

npx capybara-mcp-setup --api-key <your-api-key>

For Claude Code:

claude mcp add capybara-mcp -e CAPYBARA_API_KEY=<your-api-key> -- npx -y capybara-mcp

2. Environment variables

| Variable | Required | Description | |----------|----------|-------------| | CAPYBARA_API_KEY | Yes | Your Capybara API key | | CAPYBARA_SKIP_GIT_CHECKPOINT | No | Set to 1 to disable safety commits before overwriting files | | CAPYBARA_GIT_AUTHOR_NAME | No | Author name for checkpoint commits (default capybara-mcp) | | CAPYBARA_GIT_AUTHOR_EMAIL | No | Author email for checkpoint commits (default [email protected]) |

The API endpoint is built in (https://caoybaramcp-production.up.railway.app/v1). No other env vars needed.

3. Run manually

CAPYBARA_API_KEY=<key> npx capybara-mcp

How it works

1. The agent calls generate_assets with asset specs (maps, characters, etc.).
2. The client reads src/data/assets.md and existing JSON from your game repo.
3. Assets are generated via the Capybara API and written back to disk.
4. Live progress is written to .capybara/status.active.md (rewritten in place; cleared on success). Cancelled runs go to status.cancelled.md (keep job_id for recovery); failures go to status.failed.md.

Git safety checkpoint

When generation would overwrite an existing file, the client tries to preserve the previous version in git (best-effort):

• If the file has uncommitted changes (or is untracked but present), those contents are committed first as capybara-mcp: checkpoint before overwriting….
• If the file is already clean at HEAD, no commit is made — git restore -- <path> still recovers the prior version after the write.
• Skipped when not a git repo, git is unavailable, the path is gitignored, or CAPYBARA_SKIP_GIT_CHECKPOINT=1.
• Checkpoint failures never block writing assets; the tool summary notes skips/errors.

To undo a generation write before you commit the new files:

git restore -- path/to/file

If interrupted, use get_job_status with the returned job_id.

Requirements

• Node.js 18+
• A Capybara API key with sufficient credits
• A game project with src/data/assets.md (for non-first-build generation)

License

MIT