MCP GDScript Server

You can run the GDScript MCP server to analyze GDScript code structure efficiently, extract symbols, and understand dependencies without loading entire files. This enables faster AI-assisted code understanding across large Godot projects and makes code navigation and refactoring safer.

How to use

Use the MCP server with your client to analyze GDScript code snippets, files, or projects. You can run it locally to process code directly or connect to a remote MCP server if you prefer centralized analysis. Typical workflows include inspecting file structures, locating symbols like functions or signals, and identifying dependencies such as extends, preload, and import statements. You can also analyze code snippets without accessing files to test parsing and structure extraction in isolation.

How to install

Prerequisites: Python 3.10 or later and a runtime environment for the hosting command. You will also need a working Python package installation workflow (pip) and a node/utility runner if you choose to use the additional distribution methods.

Choose one of the following installation methods. Each method shows you how to run the MCP server for GDScript analysis.

{
  "mcpServers": {
    "gdscript": {
      "command": "uvx",
      "args": ["mcp-gdscript"]
    }
  }
}

{
  "mcpServers": {
    "gdscript": {
      "command": "npx",
      "args": ["mcp-gdscript"]
    }
  }
}

# Local installation

# Clone the repository
git clone https://github.com/minami110/mcp-gdscript
cd mcp-gdscript

# Install in development mode
pip install -e .

# Run the server
mcp-gdscript

Additional setup for local run

If you prefer a direct, local execution after installation, you can run the server as a standard command. The typical flow is to install the package in development mode and start the server with its entry command.

Configuration references

Configuration is provided through MCP client connections. The following examples show how to configure the server in your MCP client so it can receive analysis requests.

Available tools

analyze_gdscript_file

Analyze a GDScript file and extract its complete structure including symbols like classes, functions, signals, variables, and enums along with line numbers.

get_gdscript_structure

Get a human-readable, formatted view of a GDScript file structure with line numbers.

find_gdscript_symbol

Search for a specific symbol in a GDScript file and return its type and location.

get_gdscript_dependencies

Extract extends, preload, and import statements from a GDScript file.

analyze_gdscript_code

Analyze raw GDScript code provided as a string and return a full structure, symbols, and summary.

set_project_root

Set the root directory for project-wide GDScript analysis and index files.

get_project_root

Retrieve the current project root and indexed GDScript file count.

find_references

Find all references to a symbol either project-wide or within a specific file.