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

1. Install dependencies:

   pip install -e .
   

2. 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.

1. Auto-detection: The server automatically scans common installation paths
2. Confirmation: You'll be prompted to confirm or provide the simulator location
3. 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=true to 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 early
• get_simulator_screenshot - Get screenshot(s) for visual analysis
  • which="latest" - Capture fresh screenshot now (default)
  • which="last" - Get most recent from recording session
  • which="all" - List all recorded screenshots
  • which="5" - Get specific recorded screenshot by number
• list_screenshots - List all available screenshots with file sizes
• simulate_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:

1. The server creates a _mcp_logger.lua file in your project directory
2. Automatically injects require("_mcp_logger") into your main.lua (if not already present)

The logger is inserted intelligently:

• After mobdebug if present
• Before other require statements 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.lua truncates the file when Solar2D starts
• Use read_solar2d_logs tool to view logs anytime, regardless of how Solar2D was launched
• The MCP server only reads the log file - _mcp_logger.lua is responsible for all writing

Capturing Screenshots

The MCP server can capture screenshots from the running simulator for visual analysis!

How It Works

1. Auto-injected module: When you run a project, _mcp_screenshot.lua is created and injected into main.lua
2. Control file signaling: The MCP server writes to a control file to start/stop recording
3. Periodic capture: Screenshots are captured every 100ms (10 fps) while recording is active
4. 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

1. Auto-injected module: _mcp_touch.lua is created and injected into main.lua
2. Hit testing: The module finds touchable objects at the tap location
3. 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.

Resources

• MCP Documentation
• Solar2D Documentation
• MCP Python SDK