mcp-gdscript
A Model Context Protocol (MCP) server for GDScript code analysis. This server allows AI assistants to understand GDScript code structure without reading entire files, making it efficient for large codebases.
Features
File Structure Analysis: Extract classes, functions, signals, variables, and enums from GDScript files
Symbol Search: Find specific symbols and get their location and type
Dependency Extraction: Identify extends, preload, and import statements
Direct Code Analysis: Analyze GDScript code snippets without file I/O
Tree-Sitter Powered: Accurate parsing using the official GDScript tree-sitter grammar
Installation & Usage
With uvx (Recommended)
The simplest way to use this server - no installation required:
With npm/npx
Local Installation
Available Tools
1. analyze_gdscript_file
Analyze a GDScript file and extract its complete structure.
Input:
file_path(string): Path to the .gd or .gdscript file
Output: Returns JSON with:
symbols: Lists of classes, functions, signals, variables, and enums with line numberssummary: Total counts for each symbol type
Example:
2. get_gdscript_structure
Get a human-readable structure view of a GDScript file.
Input:
file_path(string): Path to the .gd or .gdscript file
Output: A formatted text representation showing the file structure with line numbers.
Example output:
3. find_gdscript_symbol
Search for a specific symbol in a file.
Input:
file_path(string): Path to the .gd or .gdscript filesymbol_name(string): Name of the symbol to find
Output: Symbol information including type, name, and location.
Example:
4. get_gdscript_dependencies
Extract all dependencies from a GDScript file.
Input:
file_path(string): Path to the .gd or .gdscript file
Output: Lists of extends, preload, and import statements.
Example:
5. analyze_gdscript_code
Analyze GDScript code provided directly as a string.
Input:
code(string): GDScript source code
Output: Complete analysis including structure, symbols, and summary.
Use Cases
Codebase Navigation: Quickly understand the structure of large GDScript files
API Documentation: Generate documentation from code structure
Dependency Analysis: Understand script relationships and dependencies
Code Review: Get structure overview before detailed review
Refactoring Aid: Understand what needs to be updated when refactoring
Configuration
Environment Variables
RUST_LOG: Set logging level (e.g.,debug,info,warn)
Performance Tips
For large files (>10MB), the server efficiently extracts structure without loading full content into context
Symbol extraction is optimized for typical GDScript files (< 50MB)
The tree-sitter parser uses cached grammar for performance
Limitations
Currently optimized for GDScript 4.x and later
Complex macro expansions may not be fully analyzed
Some edge cases in dynamic code patterns may not be captured
Development
Setup
Testing
Code Style
Contributing
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Make your changes
Submit a pull request
License
MIT License - see LICENSE file for details
References
Troubleshooting
"Module not found" errors
Make sure you're using Python 3.10 or later and have installed the server correctly.
Parse errors for GDScript 3.x
This server is optimized for GDScript 4.x. For GDScript 3.x, some features may not work as expected.
Performance issues
If analyzing very large files, consider:
Splitting large scripts into smaller modules
Using the structure tool instead of full analysis
Analyzing specific symbols instead of entire files
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables AI assistants to analyze GDScript code structure, extract symbols, functions, and dependencies without reading entire files. Supports efficient navigation and understanding of Godot game engine codebases through tree-sitter parsing.