Skip to main content
Glama

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 .

    Optional extras for the experimental integrations:

    pip install -e ".[trello,social]"

    Video recording (macOS) needs the Xcode command line tools (swiftc builds the recorder on first use), ffmpeg for exports (brew install ffmpeg), and Screen Recording permission for the terminal/app that launches the MCP server (System Settings > Privacy & Security > Screen & System Audio Recording).

    The SolarScope test tools need the SolarScope runtime added to your game (see SolarScope Tests).

  2. Test the server:

    python server.py

Related MCP server: LÖVE2D MCP Server

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

  • get_simulator_screenshot - Get a still for visual analysis

    • Default: capture the live simulator now

    • video_time - pull a full-resolution still out of a video recording instead (recording picks one, default the newest; save_to writes the full-res PNG)

  • start_video_recording - Record the simulator window as video (see Recording Video)

    • Native Retina resolution, 60fps, the simulator's own audio, title bar cropped off

    • duration (default 60s, max 600s), name, fps, codec (hevc / prores), audio, crop

  • stop_video_recording - Stop it, wait for the file, report frames and delivered fps

  • export_video - Cut a recording for delivery: presets x (1920x1080 60fps), youtube (2560x1440 60fps), vertical (1080x1920, aim with focus_x), preview (960px 30fps), master (ProRes 422 HQ); trim with start/end

  • list_video_recordings - Recordings and exports with duration, size and resolution

  • 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

  • simulate_drag - Drag/swipe between two points on the simulator screen

    • Percentage-based start and end bounding boxes

    • Configurable drag duration

    • Useful for swipes, card plays, and sliders

  • find_object - Locate touchable display objects on screen

    • Reports positions so taps/drags can be targeted precisely

  • get_display_info - Get display coordinate system info

Game State & Scenarios

  • get_game_state - Get structured game state as JSON

    • Returns current scene, combat state, player stats, and UI state

    • Much faster and more reliable than parsing screenshots

  • run_scenario - Configure and launch a test scenario without restarting

    • Load a saved scenario from scenarios/ or pass settings inline

    • Optionally seed math.random for deterministic replay

    • Supports scripted scenarios with a steps array that runs a pass/fail test (actions: wait_for, verify, wait, tap, drag, play_card, tap_stat, tap_choice)

  • list_scenarios - List saved scenario files from the project's scenarios/ folder

SolarScope Tests

Drive SolarScope, an in-game test framework for Solar2D ("Playwright for Solar2D"). Tests are plain Lua that run inside the simulator. They drive the real UI through hit-tested input and assert on structured game state.

Optional dependency. SolarScope is only needed for the three tools below. The rest of the server works without it. These tools don't install SolarScope. They write a command to <project>/.solar_scope/command.json and read the result the framework writes to the simulator sandbox, so the game must already include the SolarScope runtime. To add it, copy solar_scope.lua and the solar_scope/ folder from the SolarScope repo into your project. See its README for details.

Results are read from ~/Library/Application Support/Corona Simulator/<project>-*/Documents/solar_scope/, so these tools currently work on macOS only.

  • run_solar_scope_test - Launch the project running a specific test module (e.g. tests.regression.match_clears) without editing the game's config

    • Replaces any running instance

    • Returns a command sequence number for get_solar_scope_result

  • rerun_solar_scope_test - Hot-reload a test into an already-running simulator

    • Much faster than relaunching when iterating on a test

  • get_solar_scope_result - Read the structured result of the latest run (status, message, errors, artifacts, probe report)

    • Pass wait_seq to poll until that run's result appears (timeout_ms, default 8000)

Resources

  • solar2d://info - Server information

Experimental / WIP

These integrations are in progress and their tool surface may change:

  • Trello - Manage a project board from the assistant: configure_trello, setup_trello_board, create_trello_card, list_trello_cards, get_trello_card, update_trello_card, comment_trello_card, attach_to_trello_card

  • Social media - Draft and publish posts: configure_social_media, preview_social_post, publish_social_post

  • AI art (OpenAI GPT Image / Black Forest Labs FLUX) - Generate sprites, backgrounds, icons and UI art (pip install -e ".[art]"):

    • configure_art_generation - Save API keys, check them (OpenAI: image models the key can use; BFL: credit balance), pick the default_provider (openai or bfl) and default models. Keys go in ~/.config/solar2d-mcp/config.json (owner-only permissions), never the project; OPENAI_API_KEY / BFL_API_KEY in the server's environment work too. Optional OpenAI organization_id / project_id send requests under a specific org or project.

    • generate_art - Prompt to image. provider, model, size, n variations, output_format, background: transparent for sprites (see below). OpenAI only: quality (low for drafts). BFL only: seed.

    • edit_art - Rework existing images or draw new art that matches them: pass reference images (sprites, a simulator screenshot). OpenAI only: a mask to redraw one region.

    • Files are saved full-size to save_to (e.g. <project>/images/hero.png) or ~/Pictures/solar2d-mcp/<project>/art/; the tool returns a downscaled preview.

    • OpenAI: default gpt-image-2.5-sunburst (gpt-image-2 is deprecated). GPT Image models need OpenAI organization verification; an org without image access gets 429 "TPM: Limit 0".

    • remove_background - Make any image's background transparent, locally and free: chroma keys out a flat colour (crisp pixel-art edges, clears enclosed gaps), vision uses Apple's on-device subject cutout for busy or painted backgrounds (macOS 14+, capture/cutout.swift compiled on first use), auto picks chroma when the border is one flat colour, difference computes partial alpha from the same art on white (image) and on black (black_image).

    • Black Forest Labs: default flux-2-pro; also flux-3-image (newest, up to 10 references), flux-2-max, flux-2-flex, flux-2-klein-9b. Tasks are submitted, polled and downloaded automatically; an account without credits gets 402.

    • Transparent sprites with BFL: no FLUX model outputs alpha, so background: transparent asks for the art on flat magenta (transparent references are flattened onto it too), then removes it locally: chroma key with de-spill of tinted edges, and a cast shadow drawn on the background becomes a soft black shadow (keep_shadows: false drops it). Transparent pixels are zeroed so texture filtering can't bleed colour. The un-cut image is kept as <name>-original.png so a cutout can be redone with remove_background at no cost.

    • cutout: "difference" for glows, sparkles, smoke, glass and soft shadows: the art is rendered on white, then that render is edited onto black, and alpha is computed from the pair (a = 1 - (white - black)/255, colour un-mixed from both), so effects come out genuinely semi-transparent instead of cut or solid. Uses flux-2-pro unless model is passed (whatever bfl_default_model is). Costs two renders (~7.5c). If the black edit doesn't repaint the background (flux-3-image ignored it in testing) or the renders don't line up, the black pass is retried with flux-2-pro, then falls back to an Apple Vision cutout of the white render. Both renders are kept as <name>-white.png / <name>-black.png; remove_background with method: "difference" and black_image re-mattes them for free.

Possible Plans

  • More complex ability to "play", based on "watching"

  • 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  # get_simulator_screenshot (live or from a recording)
│   ├── video.py       # 60fps window recording + export presets
│   ├── touch.py       # Touch/drag simulation tools
│   ├── state.py       # Game state & test scenario tools
│   ├── solar_scope.py # SolarScope test-runner tools
│   ├── art/           # OpenAI / Black Forest Labs image generation tools (experimental)
│   ├── social/        # Social media tools (experimental)
│   └── trello/        # Trello board tools (experimental)
├── capture/
│   ├── simcap.swift   # ScreenCaptureKit window recorder (built to capture/.build/)
│   └── cutout.swift   # Apple Vision subject cutout for remove_background (built to capture/.build/)
├── 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"

  • "Record 20 seconds of gameplay and export it for X"

  • "Run the SolarScope test tests.regression.match_clears and report the result"

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: <tempdir>/corona_log_<project-name>.txt, where <tempdir> is Python's tempfile.gettempdir() ($TMPDIR, usually under /var/folders/... on macOS)

  • 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

get_simulator_screenshot writes "now" to a control file; the auto-injected _mcp_screenshot.lua saves one JPEG at content resolution to <tempdir>/solar2d_screenshots_<project-name>/screenshot_latest.jpg and the tool returns it. Nothing in the game runs per frame for it.

Recording Video

Video is recorded outside the game, from the simulator's window, by capture/simcap (ScreenCaptureKit; compiled from capture/simcap.swift the first time it is needed). The game does no work for it, so a recording runs at the simulator's own frame rate (60fps) instead of the stuttering 10fps a display.save loop could manage.

  • Picture: the simulator window at native Retina pixels (a 1728x972pt window is 3456x1944), cropped to the game's content aspect so the title bar is gone. The aspect comes from the display info the touch module writes; crop: false keeps the whole window. The window can sit behind other windows, but not be minimized.

  • Sound: the simulator's own audio only, not the rest of the machine.

  • Frames: ScreenCaptureKit only sends a frame when the window changed, so a still screen lowers the delivered count. Exports are constant frame rate.

  • Masters are kept in ~/Movies/solar2d-mcp/<project>/<name>.mov (HEVC ~60Mbps, or ProRes 422 HQ with codec: prores); exports go to its exports/ folder.

  • Control: the recorder runs detached and stops on stop_video_recording, after duration, or on SIGINT. Its state lives in <tempdir>/solar2d_video_<project>.json, so any MCP server process can stop a recording another one started.

  • Markers: simulate_tap / find_object draw indicators into the game frame. Drive takes meant for posting with a SolarScope harness instead.

User: Record the boss intro and give me something for X
Assistant: [start_video_recording name="boss-intro" duration=40]
           [run_solar_scope_test test="tests.regression.boss_intro"]
           [stop_video_recording]
           [export_video preset="x" start=2 end=32]

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

License

MIT © 2025-2026 Under Byte Studios, LLC

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to build, run, and debug Godot projects by editing scenes and scripts, inspecting live game state, injecting input, capturing viewports, and examining native debugger state through 42 tools.
      European Union Public 1.2
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to interact with running games in real time — introspecting game state, simulating keyboard and mouse input to actually play, capturing screenshots, executing Lua code, hot-reloading files, and receiving push notifications when state changes.
      8
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to launch a game engine editor, run and debug projects, capture console output, and manage scenes, nodes, sprites, and UIDs.
      14
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to operate directly inside a running Unity Editor project, creating scenes, generating scripts, simulating input, capturing screenshots, inspecting performance, and automating editor tasks through its built-in tools and resources.
      MIT