Swallowtail

Godot automation. Your game. Your workflow.

Build, inspect, test, and debug Godot games from your terminal. Automate repetitive work with scripts, or let an agent use the same commands. No agent, model, or AI account is required. MCP is an optional interface.

[!NOTE] This project shipped as godot-mcp through 0.11. That name described one connector, and the toolkit automates Godot from a terminal, a shell script, or a connected client, with MCP as one optional interface. The old name also matched many other Godot MCP projects. Swallowtail names the toolkit itself. The repository URL, the Go module path, and the godot-mcp executable are unchanged, with no scheduled removal date.

Use swallowtail for new commands and scripts. Release bundles also include the deprecated godot-mcp executable with identical functionality. Preview an existing project's addon migration with swallowtail migrate --project DIR. See Migrating to Swallowtail. The project is MIT licensed.

Terminal quickstart · Scripting and CI · Command reference · Releases

Contents

1. Your game. Your workflow. (lines 58-80)
2. Working with Godot's built-in CLI (lines 82-97)
3. Game QA and release reports (lines 99-114)
4. Playtest sessions and CI reports (lines 116-132)
5. CLI first, MCP optional (lines 134-146)
6. How it compares (lines 148-169)
7. Why I built Swallowtail (lines 171-195)
8. Samples (lines 197-203)
9. Contributing (lines 205-217)
10. How it works (lines 219-231)
11. Requirements (lines 233-249)
12. Build (lines 251-257)
13. Install into a project (lines 259-279)
14. Quick start (lines 281-319)
15. Use as an MCP server (lines 321-356)
16. Live dashboard (opt-in) (lines 358-368)
17. Build on it (lines 370-380)
18. Command groups (lines 382-386)
19. Agent skill (lines 388-390)
20. Layout (lines 392-403)
21. License (lines 405-407)

Your game. Your workflow.

• Run commands: inspect a scene, change a property, validate it, and play the result.
• Automate your workflow: turn repeatable work into shell scripts, checks, and playtests. Use JSON output and exit codes to connect the steps.
• Add your own commands: drop a GDScript file into res://mcp_commands/ and it shows up in the CLI, in help, and as an MCP tool. See Add your own commands.
• Connect your tools: expose the same operations through the CLI or an MCP client. Choose the task and review what changes.

From a project with the addon enabled:

swallowtail scene tree
swallowtail scene validate --path res://hello.tscn
swallowtail scene play --mode res://hello.tscn
swallowtail runtime tree
swallowtail scene stop