Godot4 Runtime MCP

🚀 Example Godot Project

This directory contains a simple Godot 4 example project demonstrating the use of the MCP plugin.

🚀 Quick Start

Project Structure

ExampleProject/
├── project.godot          # Godot project configuration
├── addons/
│   └── mcp_client/        # MCP plugin (copied from the parent directory)
├── scenes/
│   ├── main.tscn          # Main scene
│   └── player.tscn        # Player scene
└── scripts/
    └── Player.cs          # Player script

How to Use

1. Create a Godot Project

In the Godot editor:

1. Create a new project.
2. Select C# as the scripting language.
3. Save the project.

2. Install the MCP Plugin

# From the project root directory
cp -r GodotPlugin ExampleProject/addons/mcp_client

Or manually copy the GodotPlugin folder to ExampleProject/addons/mcp_client.

3. Enable the Plugin

1. Open the project in the Godot editor.
2. Go to Project -> Project Settings -> Plugins.
3. Enable "MCP Client".

4. Create a Test Scene

Main Scene (main.tscn)

Create the node structure:

Main (Node2D)
├── Player (CharacterBody2D)
│   └── Sprite2D
└── Camera2D

Player Script (Player.cs)

using Godot;

public partial class Player : CharacterBody2D
{
    [Export]
    public float Speed { get; set; } = 200.0f;
    
    [Export]
    public int Health { get; set; } = 100;

    public override void _PhysicsProcess(double delta)
    {
        Vector2 velocity = Velocity;
        Vector2 direction = Input.GetVector("ui_left", "ui_right", "ui_up", "ui_down");
        
        if (direction != Vector2.Zero)
        {
            velocity = direction * Speed;
        }
        else
        {
            velocity = Vector2.Zero;
        }

        Velocity = velocity;
        MoveAndSlide();
    }
    
    public void TakeDamage(int damage)
    {
        Health -= damage;
        GD.Print($"Player took {damage} damage. Health: {Health}");
        
        if (Health <= 0)
        {
            Die();
        }
    }
    
    public void Heal(int amount)
    {
        Health += amount;
        GD.Print($"Player healed {amount}. Health: {Health}");
    }
    
    private void Die()
    {
        GD.Print("Player died!");
        // You can add death logic here
    }
}

5. Run and Test

1. Start the MCP server.

./start-server.sh

2. Run the game in Godot (F5).
3. Test the MCP tool in Claude.

💻 Usage Examples

Basic Operations

1. View the Scene Tree

Get the current scene tree structure

2. View Player Information

Get detailed information about the node /root/Main/Player

3. View Player Properties

Get the Speed and Health properties of /root/Main/Player

Modification Operations

4. Modify the Speed

Set the Speed property of the player to 500

5. Modify the Position

Set the player's position to (400, 300)

6. Call a Method

Call the TakeDamage method of /root/Main/Player with the parameter [20]

Advanced Operations

7. Create a New Node

Create a CharacterBody2D node named "Enemy" under /root/Main

8. Performance Monitoring

Get the current performance statistics

9. Take a Screenshot

Take a screenshot of the current game screen and save it

Expected Results

Scene Tree Output

{
  "path": "/root",
  "name": "root",
  "type": "Window",
  "children": [
    {
      "path": "/root/Main",
      "name": "Main",
      "type": "Node2D",
      "children": [
        {
          "path": "/root/Main/Player",
          "name": "Player",
          "type": "CharacterBody2D",
          "children": [...]
        }
      ]
    }
  ]
}

Node Information Output

{
  "path": "/root/Main/Player",
  "name": "Player",
  "type": "CharacterBody2D",
  "properties": {
    "position": {"x": 0, "y": 0},
    "Speed": 200,
    "Health": 100
  },
  "methods": ["TakeDamage", "Heal", "_PhysicsProcess", ...],
  "signals": [...]
}

🔧 Troubleshooting

Plugin Not Loaded

• Check if the plugin files are in the correct location.
• Ensure that the plugin.cfg file is in the correct format.
• Restart the Godot editor.

Unable to Connect to the MCP Server

• Confirm that the MCP server is running.
• Check that port 7777 is not occupied.
• View the error information in the Godot console.

Incorrect Node Path

• Use get_scene_tree to confirm the correct node path.
• Node paths are case-sensitive.
• Ensure that you are using an absolute path (starting with /root).

🚧 Extended Exercises

1. Create Multiple Enemies
   • Create 5 - 10 enemies using create_node.
   • Set a random position for each enemy.
2. Performance Optimization
   • Monitor the FPS.
   • Use get_scene_tree to find the number of nodes.
   • Try to delete unnecessary nodes.
3. Game Balance Adjustment
   • Dynamically adjust the player's speed.
   • Test different Health values.
   • Adjust the game difficulty in real-time.
4. Debugging Workflow
   • Modify variables while the game is running.
   • Test boundary cases.
   • Verify the game logic.

🚀 Next Steps

• Create more complex scenes.
• Add more game logic.
• Use the MCP tool for AI-assisted development.
• Explore the possibility of automated testing.