Solar2D MCP Server
A Model Context Protocol (MCP) server for working with Solar2D (Corona SDK) projects. This server enables AI assistants to run, debug, and interact with Solar2D games.
Works with any MCP-compatible client, including:
- Claude Code CLI
- Other AI assistants that support MCP
- Custom integrations
Setup
-
Install dependencies:
pip install -e . -
Test the server:
python server.py
Configuration
Claude Desktop
Add this configuration to your Claude Desktop config file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"solar2d": {
"command": "/path/to/solar2d-mcp/.venv/bin/python",
"args": [
"/path/to/solar2d-mcp/server.py"
]
}
}
}
After adding the configuration, restart Claude Desktop.
Claude Code CLI
Add the server using the claude mcp add command:
claude mcp add --scope user --transport stdio solar2d \
/path/to/solar2d-mcp/.venv/bin/python \
/path/to/solar2d-mcp/server.py
Verify the server is connected:
claude mcp list
You can also add it to a specific project using --scope project or create a .mcp.json file in your project root.
First-Time Setup
On first use, the server needs to know where your Solar2D Simulator is installed.
- Auto-detection: The server automatically scans common installation paths
- Confirmation: You'll be prompted to confirm or provide the simulator location
- Remembered: Your choice is saved to
~/.config/solar2d-mcp/config.json
Example first-run flow:
User: Run my Solar2D project
Assistant: Solar2D simulator needs to be configured. Detected:
- /Applications/Corona-3726/Corona Simulator.app/Contents/MacOS/Corona Simulator
Use configure_solar2d with confirm=true to use this path.
User: Yes, use that one
Assistant: [calls configure_solar2d(confirm=true)]
✓ Solar2D simulator confirmed and saved!
Features
Tools
configure_solar2d- Configure the Solar2D simulator path- Auto-detects installed simulators
- Persists configuration across sessions
- Use
confirm=trueto accept detected path - Or provide custom path with
simulator_path="..."
run_solar2d_project- Run a Solar2D project in the simulator- Accepts project directory or main.lua path
- Optional debug and console flags
- Launches simulator in background
- Injects logger that captures all print() output
read_solar2d_logs- Read console logs from running Solar2D Simulator- View all Lua print() statements from your game code
- Configurable number of recent lines to display
- Helps debug your Lua code in real-time
- Automatic setup: Logger is auto-injected into main.lua on first run
- Note: Only captures Lua print() output, not Solar2D system messages
list_running_projects- List all tracked Solar2D Simulator instances- Shows PID, status, and log file location
- Useful for managing multiple running projects
start_screenshot_recording- Start capturing screenshots from the simulator- Captures at 10 fps (100ms interval)
- Default recording duration: 60 seconds (max: 300 seconds / 5 minutes)
- Can extend recording while already capturing
stop_screenshot_recording- Stop screenshot recording earlyget_simulator_screenshot- Get screenshot(s) for visual analysiswhich="latest"- Capture fresh screenshot now (default)which="last"- Get most recent from recording sessionwhich="all"- List all recorded screenshotswhich="5"- Get specific recorded screenshot by number
list_screenshots- List all available screenshots with file sizessimulate_tap- Tap/click on the simulator screen- Uses percentage-based bounding box (left, right, top, bottom)
- Taps the center of the specified area
- Example: button at 30-50% horizontal, 60-70% vertical
get_display_info- Get display coordinate system info
Resources
solar2d://info- Server information
Possible Plans
- More complex ability to "play", based on "watching"
- Swipe/drag gestures
- Built-in Skills
- Conventions & Good Practices
- Common Patterns / Templates
Development
The server uses the Model Context Protocol (MCP) Python SDK.
Project Structure
solar2d-mcp/
├── server.py # MCP server entry point
├── config.py # Configuration management and auto-detection
├── utils.py # Shared utilities
├── tools/
│ ├── __init__.py # Tool dispatcher
│ ├── configure.py # configure_solar2d tool
│ ├── run_project.py # run_solar2d_project tool
│ ├── read_logs.py # read_solar2d_logs tool
│ ├── list_projects.py # list_running_projects tool
│ ├── screenshot.py # Screenshot recording tools
│ └── touch.py # Touch simulation tools
├── resources/
│ ├── __init__.py # Resource dispatcher
│ └── info.py # solar2d://info resource
├── pyproject.toml # Project dependencies and metadata
└── README.md # This file
Testing
Once configured, you can test the server with prompts like:
- "Configure Solar2D" (first-time setup)
- "Run my Solar2D project at /path/to/my-game"
- "Launch the Solar2D simulator with debug enabled for my project"
- "Show me the logs from my running Solar2D project"
- "Read the last 100 lines of Solar2D logs"
- "List all running Solar2D projects"
Capturing Lua print() Output
The MCP server automatically captures all your Lua print() statements!
Setup (One-time)
Run your project once through MCP:
- The server creates a
_mcp_logger.luafile in your project directory - Automatically injects
require("_mcp_logger")into yourmain.lua(if not already present)
The logger is inserted intelligently:
- After
mobdebugif present - Before other
requirestatements if no mobdebug - At the start of the file otherwise
Works with Manual Launches!
Once the logger is injected, it works forever - even when you launch Solar2D manually from your IDE or command line!
- Log file location:
/tmp/corona_log_<project-name>.txt(predictable, based on project directory name) - All Lua
print()output is captured automatically by_mcp_logger.lua - Your prints still display normally in the console (Solar2D's output)
- Log file is cleared on each launch -
_mcp_logger.luatruncates the file when Solar2D starts - Use
read_solar2d_logstool to view logs anytime, regardless of how Solar2D was launched - The MCP server only reads the log file -
_mcp_logger.luais responsible for all writing
Capturing Screenshots
The MCP server can capture screenshots from the running simulator for visual analysis!
How It Works
- Auto-injected module: When you run a project,
_mcp_screenshot.luais created and injected intomain.lua - Control file signaling: The MCP server writes to a control file to start/stop recording
- Periodic capture: Screenshots are captured every 100ms (10 fps) while recording is active
- JPEG compression: Images are saved as JPEG at content resolution for smaller file sizes
Screenshot Location
Screenshots are saved to: /tmp/solar2d_screenshots_<project-name>/
The directory is cleared when the simulator starts, but screenshots persist across recording sessions within the same run.
Recording Workflow
User: Start recording screenshots for 30 seconds
Assistant: [calls start_screenshot_recording with duration=30]
User: Show me what the game looks like now
Assistant: [calls get_simulator_screenshot with which="latest"]
[displays the screenshot for visual analysis]
User: Stop recording early
Assistant: [calls stop_screenshot_recording]
Extending Recordings
You can call start_screenshot_recording while already recording to extend the duration. Screenshots continue from where they left off (not reset).
Touch Interaction
The MCP server can simulate taps on the running simulator, allowing the AI to interact with your game!
How It Works
- Auto-injected module:
_mcp_touch.luais created and injected intomain.lua - Hit testing: The module finds touchable objects at the tap location
- Event dispatch: Synthetic touch events are sent to the target object
Percentage-Based Coordinates
Taps use a bounding box with percentage coordinates (0-100):
left,right: Horizontal bounds (0=left edge, 100=right edge)top,bottom: Vertical bounds (0=top edge, 100=bottom edge)
The tool taps the center of the bounding box. This makes it easy for the AI to estimate positions visually from screenshots.
Example Workflow
User: Click on the play button
Assistant: [calls get_simulator_screenshot to see current state]
I can see a play button in the center of the screen.
[calls simulate_tap with left=40, right=60, top=45, bottom=55]
Tapped the play button!
User: Click on any popup buttons you see
Assistant: [calls get_simulator_screenshot]
I see a "Continue" button at the bottom of the screen.
[calls simulate_tap with left=30, right=70, top=80, bottom=90]
Tapped the Continue button.