Solar2D

You can run, test, and control Solar2D projects through a dedicated MCP server that connects with your AI assistants. This server lets you start a Solar2D simulator, inject a logger for Lua prints, read logs in real time, capture screenshots, and simulate taps to interact with your game, all through MCP-enabled clients.

How to use

Connect with an MCP client to manage Solar2D projects. You can install and run the server locally, then use a client to start a project, view logs, capture screenshots, and simulate touches. The server automatically captures Lua print() output, and you can read logs at any time. You can run multiple projects, monitor their status, and retrieve screenshots for quick visual analysis. For first-time setup, you will configure the Solar2D simulator path, then start running projects and use the provided tools to interact with your game.

Key capabilities you’ll use repeatedly include launching a project in the simulator, inspecting live logs, recording screenshots, and sending taps to the simulator screen to interact with UI elements. Each action is exposed as a tool you can call via your MCP client, enabling a smooth, automated workflow for testing and debugging Solar2D games.

How to install

Prerequisites: you need Python and a working Solar2D environment. You will install the MCP server in editable mode and run the server to expose the MCP interface.

pip install -e .

Test that the MCP server starts correctly by running the server entry point.

python server.py

Configuration and usage notes

The server works with MCP clients such as Claude Code CLI or Claude Desktop. You configure the connection so your client can start the server process, run solar2d projects, and access the available tools.

Configuration examples for clients

{
  "mcpServers": {
    "solar2d": {
      "command": "/path/to/solar2d-mcp/.venv/bin/python",
      "args": [
        "/path/to/solar2d-mcp/server.py"
      ]
    }
  }
}

If you prefer using a CLI to register the server with Claude, you can add it with a single command as shown below.

claude mcp add --scope user --transport stdio solar2d \
  /path/to/solar2d-mcp/.venv/bin/python \
  /path/to/solar2d-mcp/server.py

After adding the server, verify the connection to ensure the client can communicate with the MCP server.

claude mcp list

First-time setup for the Solar2D simulator

During the first run, the server auto-detects installed Solar2D simulators and asks you to confirm the path. Your choice is saved for future runs.

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!

Tools you will use

The MCP server exposes a suite of tools to manage Solar2D projects and gather data for debugging and testing. Use these tools to configure the simulator, run projects, read logs, manage screenshots, and simulate interactions.

Resources and interactions

You can access server information and related Solar2D capabilities through the MCP interface. The server integrates with the Solar2D runtime to provide a seamless debugging and testing workflow.

Development notes

The server is implemented in Python and leverages the MCP Python SDK. It includes a modular structure with dedicated tools for configuration, project execution, log reading, screenshots, and touch simulation. This design makes it straightforward to extend with additional features in the future.

Testing and common prompts

Once configured, you can test with prompts like configuring Solar2D, running a project, launching the simulator with debugging, showing logs, reading log lines, listing running projects, and capturing screenshots. These workflows help you validate behavior and iterate on development quickly.

Capturing Lua print output

Lua print() statements from your game are captured automatically by the server and stored in a log file. You can read the latest logs at any time to diagnose issues without altering your project code.

Capturing Screenshots

Screenshots can be captured from the running simulator at high frequency to provide visual context for debugging. These images are stored in a designated directory for quick access.

Touch interactions

The server can simulate taps on the simulator screen to aid automated UI testing. Use percentage-based coordinates to target UI elements, and the system will dispatch a synthetic touch event to the selected area.

Display and display info

You can query the simulator display information to understand coordinate systems and resolutions, which helps in crafting accurate tap targets and visual analyses.

Notes on reporting and troubleshooting

If you encounter issues connecting to the MCP server or running projects, verify that the Python environment is active and that the server process is running. Ensure the paths in your client configuration point to the correct server script, and confirm that the Solar2D simulator path is correctly configured on first use.

Available tools

configure_solar2d

Configure the Solar2D simulator path with auto-detection and confirmation options to persist across sessions.

run_solar2d_project

Launch a Solar2D project in the simulator with optional debug and console flags, running in the background and injecting a logger to capture all print() output.

read_solar2d_logs

Read and display the Lua print() output captured from the running Solar2D Simulator, with options for how many recent lines to show.

list_running_projects

List all tracked Solar2D Simulator instances with PID, status, and log file locations to help manage multiple running projects.

start_screenshot_recording

Begin capturing screenshots from the simulator at a defined frame rate and duration, with the ability to extend the recording.

stop_screenshot_recording

Stop screenshot recording before the scheduled duration ends.

get_simulator_screenshot

Capture and retrieve screenshots for visual analysis, with options to target latest, last, all, or a specific numbered image.

list_screenshots

List all available screenshots along with their file sizes for quick reference.

simulate_tap

Simulate a tap on the simulator screen using percentage-based coordinates to interact with UI elements.

get_display_info

Retrieve display coordinate system information from the Solar2D environment.