Solar2D MCP Server

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/
│   ├── _