Solar2D MCP Server
Enables the AI to run, debug, and interact with Lua-based Solar2D projects by capturing print() output, injecting debug modules, and monitoring real-time console logs.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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 .Optional extras for the experimental integrations:
pip install -e ".[trello,social]"Video recording (macOS) needs the Xcode command line tools (
swiftcbuilds 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).
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.pyVerify the server is connected:
claude mcp listYou 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 pathAuto-detects installed simulators
Persists configuration across sessions
Use
confirm=trueto accept detected pathOr provide custom path with
simulator_path="..."
run_solar2d_project- Run a Solar2D project in the simulatorAccepts 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 SimulatorView 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 instancesShows PID, status, and log file location
Useful for managing multiple running projects
get_simulator_screenshot- Get a still for visual analysisDefault: capture the live simulator now
video_time- pull a full-resolution still out of a video recording instead (recordingpicks one, default the newest;save_towrites 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 fpsexport_video- Cut a recording for delivery: presetsx(1920x1080 60fps),youtube(2560x1440 60fps),vertical(1080x1920, aim withfocus_x),preview(960px 30fps),master(ProRes 422 HQ); trim withstart/endlist_video_recordings- Recordings and exports with duration, size and resolutionsimulate_tap- Tap/click on the simulator screenUses 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 screenPercentage-based start and end bounding boxes
Configurable drag duration
Useful for swipes, card plays, and sliders
find_object- Locate touchable display objects on screenReports 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 JSONReturns 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 restartingLoad a saved scenario from
scenarios/or pass settings inlineOptionally seed
math.randomfor deterministic replaySupports scripted scenarios with a
stepsarray 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'sscenarios/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.jsonand read the result the framework writes to the simulator sandbox, so the game must already include the SolarScope runtime. To add it, copysolar_scope.luaand thesolar_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 configReplaces 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 simulatorMuch 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_seqto 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_cardSocial media - Draft and publish posts:
configure_social_media,preview_social_post,publish_social_postAI 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 thedefault_provider(openaiorbfl) and default models. Keys go in~/.config/solar2d-mcp/config.json(owner-only permissions), never the project;OPENAI_API_KEY/BFL_API_KEYin the server's environment work too. Optional OpenAIorganization_id/project_idsend requests under a specific org or project.generate_art- Prompt to image.provider,model,size,nvariations,output_format,background: transparentfor sprites (see below). OpenAI only:quality(lowfor 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: amaskto 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-2is 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:chromakeys out a flat colour (crisp pixel-art edges, clears enclosed gaps),visionuses Apple's on-device subject cutout for busy or painted backgrounds (macOS 14+,capture/cutout.swiftcompiled on first use),autopicks chroma when the border is one flat colour,differencecomputes partial alpha from the same art on white (image) and on black (black_image).Black Forest Labs: default
flux-2-pro; alsoflux-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: transparentasks 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: falsedrops it). Transparent pixels are zeroed so texture filtering can't bleed colour. The un-cut image is kept as<name>-original.pngso a cutout can be redone withremove_backgroundat 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. Usesflux-2-prounlessmodelis passed (whateverbfl_default_modelis). 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 withflux-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_backgroundwithmethod: "difference"andblack_imagere-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 fileTesting
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:
The server creates a
_mcp_logger.luafile in your project directoryAutomatically injects
require("_mcp_logger")into yourmain.lua(if not already present)
The logger is inserted intelligently:
After
mobdebugif presentBefore other
requirestatements if no mobdebugAt 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'stempfile.gettempdir()($TMPDIR, usually under/var/folders/...on macOS)All Lua
print()output is captured automatically by_mcp_logger.luaYour prints still display normally in the console (Solar2D's output)
Log file is cleared on each launch -
_mcp_logger.luatruncates the file when Solar2D startsUse
read_solar2d_logstool to view logs anytime, regardless of how Solar2D was launchedThe MCP server only reads the log file -
_mcp_logger.luais 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: falsekeeps 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 withcodec: prores); exports go to itsexports/folder.Control: the recorder runs detached and stops on
stop_video_recording, afterduration, 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_objectdraw 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
Auto-injected module:
_mcp_touch.luais created and injected intomain.luaHit 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.Resources
SolarScope - In-game Lua test framework driven by the SolarScope tools
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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Launch and verify high-fidelity mobile simulations from an AI agent.
Run your Krtuworks apps from an AI agent: setup, remote config, stats, players, bug reports.
Cloud iPhone Simulators for AI agents: build the Xcode project, read the screen, tap by label, test.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables 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
- AlicenseAqualityCmaintenanceEnables 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.8MIT
- AlicenseBqualityCmaintenanceEnables AI assistants to launch a game engine editor, run and debug projects, capture console output, and manage scenes, nodes, sprites, and UIDs.14MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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