Unity Code MCP Server 0.5

Unity Code MCP Server 0.5 Release Changes

TL;DR

• UniTask is no longer required, making installation and upgrades simpler.
• play_unity_game now delivers more reliable simulated input when Unity is unfocused or regains focus.
• Tool execution is more robust through main-thread-safe async handling and Unity-supported JSON dependencies.

✨ What's New for You?

The 0.5 release focuses on a leaner setup and more dependable automation, especially for agents that test gameplay while working outside the Unity window.

• One less package to install: UniTask has been removed from the package and from the setup flow. Unity Code MCP Server now uses a focused built-in async layer based on standard .NET tasks.
• Input that keeps working in the background: play_unity_game now handles focus changes, re-enables affected input devices, and temporarily applies the runtime settings needed for reliable simulated actions.
• Cleaner gameplay runs: Each run safely unpauses the Editor, clears stale device state, releases simulated inputs, and restores the previous pause and input settings afterward.
• More predictable Editor execution: MCP tools are marshalled onto Unity's main thread, reducing threading-related failures during scene, asset, test, and Play Mode operations.
• Better package compatibility: JSON handling now uses Unity's Newtonsoft Json package instead of bundled System.Text.Json assemblies, reducing assembly conflicts in host projects.

---

⚠️ Breaking Changes & Migration

Most users can upgrade directly; the required Unity packages are installed automatically. Custom MCP tool authors need to update their implementations.

• Remove manual UniTask setup: UniTask is no longer a requirement. You may remove it if no other package or project code depends on it.
• Async tool API changed: IToolAsync.ExecuteAsync now returns Task<ToolsCallResult> instead of UniTask<ToolsCallResult>.
• JSON API changed: Tool schemas and arguments now use Newtonsoft JToken instead of System.Text.Json.JsonElement. Update custom tools to import Newtonsoft.Json.Linq and use the current README examples.
• Dependencies are package-managed: Unity Input System 1.19.0 and Newtonsoft Json 3.2.2 are declared by the package. Existing projects should let Unity resolve them during the upgrade.

---

🚀 Key Improvements

🎮 Gameplay automation

• Focus-resilient simulated input: Press and hold actions remain reliable after Unity loses focus or cycles between focused and unfocused states.
• Safer state restoration: Temporary changes to Application.runInBackground, Input System background behavior, Game View input routing, Editor pause state, and time scale are cleaned up after every run.
• No stuck controls between calls: Input devices and queued actions are reset and released so previous gameplay commands do not leak into later runs.
• Stronger regression coverage: Expanded Play Mode tests cover repeated input, focus changes, presses, holds, and state cleanup.

⚙️ Runtime and compatibility

• Built-in Editor async support: A small task-based layer now handles Editor updates, real-time delays, cancellation, exceptions, coroutines, and main-thread dispatch without UniTask.
• Unity-native JSON dependency: MCP requests, responses, schemas, prompts, resources, and tool arguments now use Newtonsoft Json supplied through Unity Package Manager.
• Cleaner package imports: Bundled skills now live under Skills~, preventing Unity from unnecessarily importing and compiling their support files.

🤖 Agent experience

• Sharper tool contracts: Guidance for C# execution and gameplay simulation is shorter, clearer, and better aligned with each tool's actual responsibilities.
• Updated bundled skills: Script-execution and gameplay skills document the new contracts and more reliable Play Mode workflow.
• More accurate setup examples: README configuration and custom-tool samples now reflect the 0.5 APIs, with additional MCPorter CLI examples for direct tool calls.

v0.4.41

Merge 0.4 into main

• Add Restart Server menu item
• Add STDIO configuration logging

UnityCodeMcpServer 0.4

Unity Code MCP Server 0.4 Release Changes

TL;DR

• The default connection path is now the bundled file-backed STDIO bridge, not TCP.
• Agents can capture Game View screenshots with a dedicated get_unity_game_view_window_screenshot tool.
• Play Mode automation, input handling, logging, and test safety are more reliable.

✨ What's New for You?

The 0.4 release focuses on making Unity-agent workflows simpler to connect, easier to observe, and more reliable during Play Mode and test automation.

• Simpler connection to Unity: The bundled STDIO bridge now talks to Unity through a file-backed transport in .unityCodeMcpServer/messages, so you no longer need to manage TCP ports for the standard setup.
• New Game View screenshot tool: A dedicated get_unity_game_view_window_screenshot tool lets agents capture the current Game View on demand without piggybacking on gameplay input calls.
• More reliable Play Mode automation: play_unity_game now has tighter argument validation, better background execution handling, and smarter Input System asset resolution.
• Clearer logs when things go wrong: Unity logs are more structured, and both the Unity side and the STDIO bridge now emit stronger diagnostics for transport and request failures.
• Safer automated runs: Test execution and request handling were tightened so Unity is less likely to process requests at the wrong time or leave stale transport files behind.

---

⚠️ Breaking Changes & Migration

This release changes how external clients connect to Unity.

• STDIO transport changed: The Python bridge no longer forwards requests over TCP. It now exchanges request and response files through .unityCodeMcpServer/messages in the Unity project root.
• Old server-style configs should be removed: If your MCP client was configured for TCP or the earlier HTTP server flow, switch to the bundled unity-code-mcp-stdio bridge configuration from the current README.
• No standard HTTP/TCP server setup in docs: The documented default path for 0.4 is the file-backed STDIO bridge.

---

🚀 Key Improvements

📡 Transport and setup

• File-backed Unity transport: Requests are written to disk, Unity claims and deletes request files as it starts processing them, and the bridge waits only for the matching response file.
• Cleaner bridge behavior: The STDIO bridge now uses request timeouts instead of retry-based socket connection settings, which makes failures easier to reason about.
• Skills and setup guidance updated: The repo guidance and settings flow were refreshed so agents and users follow the current Unity workflow more consistently.

🕹 Play Mode and testing

• Dedicated screenshot capture: get_unity_game_view_window_screenshot is now a first-class tool with Edit Mode and Play Mode coverage.
• Smarter input asset lookup: play_unity_game resolves the InputActionAsset from settings on each call and falls back more gracefully when no explicit path is configured.
• More defensive automation flow: Play Mode operations and Unity test execution perform stronger validation around active test runs and editor state.

📊 Diagnostics and configuration

• Structured Unity console output: Console log reads now include richer metadata such as severity, making automated troubleshooting easier.
• Centralized logging: Unity-side logging was consolidated and expanded, with better context around server startup, transport activity, and failures.
• Settings UX improvements: The server settings editor was refined, including better assembly selection and clearer configuration behavior.

UnityCodeMcpServer 0.3.5-preview

Unity Code MCP Server 0.3 Release Changes

✨ What's New for You?

The 0.3 release expands Unity Code MCP Server from editor automation into guided gameplay automation, while also making day-to-day agent workflows safer and more reliable.

• New Tools: Play and Test Your Game: New tools like enter_play_mode, play_unity_game, and exit_play_mode let agents automate gameplay and testing directly in Play Mode. Agents can now enter the game, simulate Input System actions, capture screenshots and logs, and exit cleanly, making real gameplay validation part of the workflow.
• More reliable tool execution: MCP tools and automated test runs now detect Unity compilation state earlier and avoid common hangs or invalid transitions.
• Safer test workflows: Scene restore and Play Mode handling were strengthened so automated runs are less likely to leave the Editor in an unexpected state.
• Less setup for AI agents: Bundled skills are now installed and updated automatically, so agents can discover the right workflows with less manual configuration.
• Smarter built-in guidance: A new unity-game-player skill teaches agents how to inspect a running game, compute actions, and adapt during gameplay testing.

---

⚠️ Breaking Changes & Migration

This release has no breaking MCP configuration changes.

• Unity Input System dependency added: Gameplay automation now depends on the Unity Input System package, which is added automatically through the package manifest.
• Skill installation is now automatic: If you previously installed skills manually, review the configured target directory in Tools > UnityCodeMcpServer > Show or Create Settings to confirm it still matches your preferred agent setup.

---

🚀 Key Improvements

🕹 Play Mode Automation

• New tools: enter_play_mode, play_unity_game, and exit_play_mode
• play_unity_game can temporarily unpause the game, send press and hold input actions, collect gameplay logs, and return a screenshot for fast feedback loops.
• Together, these new tools let agents automate both play and gameplay testing in a closed loop, observing the game, acting on it, and re-checking results without leaving the Editor.

🛡 Reliability and Safety

• Compilation guards: Tooling now fails fast when Unity is compiling instead of waiting on operations that cannot complete safely.
• Improved scene restoration: Automated test execution does a better job restoring Editor scene state after runs.
• Play Mode test coverage: The new gameplay automation path ships with dedicated Edit Mode and Play Mode tests.

🧠 Skills and Setup

• Automatic skill updates: Built-in skills are copied during package install and update, and unchanged files are skipped.
• Clearer skills configuration: Settings now support GitHub, Claude, Agents, or Custom install targets with a clearer inspector workflow.
• New bundled skill: unity-game-player was added alongside updates to the existing script-execution skill.
• Synchronous script execution support: Editor-side script execution now supports tighter coordination with tests and automation flows.

UnityCodeMcpServer 0.2-preview

Unity Code MCP Server 0.2 Release Changes

✨ What's New for You?

The 0.2 release focuses on making your AI agent smarter out-of-the-box and giving you better tools directly inside the Unity Editor.

• Teach Your Agent, Once: Ship a built-in skill file (executing-csharp-scripts-in-unity-editor) that codifies best practices for script execution, log reading, and test running. Install it into any AI agent workspace (Copilot, Claude, etc.) with a single click — no manual copy-paste.
• Save Your Favourite Scripts: A new Favourite Scripts window lets you save, load, and run C# scripts directly from the Unity Editor. Build a personal library of automation scripts without relying on an AI agent for every repetitive task.
• Accurate Console Logs: The read_unity_console_logs tool now reads directly from the live Unity Console window instead of the on-disk log file. Logs are always scoped to the current project and delivered in tail order (oldest → newest), matching what you actually see in the Editor.

---

⚠️ Breaking Changes & Migration

This release has no breaking changes. All existing MCP client configurations remain valid.

---

🚀 Key Improvements

🧠 Skills System

• SkillsInstaller: New installer class that copies bundled skill folders into any target directory. Files whose content is unchanged are skipped, so updates are always additive and safe to re-run.
• Settings UI: The Settings inspector now includes a dedicated Skills section with preset quick-select buttons for common agent paths (.github/skills/, .claude/skills/, .agents/skills/) and a Custom folder picker for any other location.
• SkillsTargetPath Setting: New field in UnityCodeMcpServerSettings stores your chosen install path across sessions. Access via Tools > UnityCodeMcpServer > Show Settings.
• Built-in Skill — executing-csharp-scripts-in-unity-editor: A comprehensive Markdown skill document covering:
  • Which tool to use and when (execute_csharp_script_in_unity_editor, read_unity_console_logs, run_unity_tests)
  • Core scripting rules (top-level statements, synchronous-only, idempotency)
  • Forbidden anti-patterns (fake output, async, background threads)
  • Common scripting patterns and a debugging loop

🖥 Favourite Scripts Window (New Editor Tool)

• Menu: Tools > UnityCodeMcpServer > Favourite Scripts
• Save named C# scripts to a persistent JSON file (.unityCodeMcpServer/favouriteScripts.json) at the project root.
• Select a saved script from a dropdown, edit it inline, and run it immediately via ScriptExecutionService — the same execution path used by the MCP tool.
• Supports Save, Reload, Delete, and Run actions with a scrollable code editor area.

📋 Console Log Reading Fix

• UnityConsoleLogReader: New shared helper that reads log entries directly from Unity's internal ConsoleWindow.ConsoleWindowReflectHelper via reflection, replacing the previous on-disk log file approach.
  • Logs are now project-scoped — no cross-project contamination when multiple Unity instances are open.
  • Entries are returned in tail order, consistent with how the Console window displays them.
  • Both ReadUnityConsoleLogsTool and UnityConsoleLogsResource now delegate to this single reader, eliminating duplicated logic.

🏗 Infrastructure & Testing

• Added UnityConsoleLogReaderTests covering tail selection, formatting, and error handling.
• Added SkillsInstallerTests covering install, skip-unchanged, update, and error paths.
• ReadUnityConsoleLogsToolTests updated to reflect the new reader behaviour.

UnityCodeMcpServer 0.1.8-preview

Unity Code MCP Server 0.1 Release Changes

✨ What's New for You?

The 0.1 release focuses on making the Unity Code MCP Server more reliable and easier to use. Here are the highlights of how your experience will improve:

• Zero-Config Connection: You no longer need to worry about matching port numbers between Unity and your AI agent configuration. The bridge now figures it out automatically from your Unity settings.
• Reliable Server Restarts: We've overhauled how TCP connections are handled. This means the server can now restart instantly during Unity domain reloads or manual clicks without hitting "Address already in use" errors—significantly improving day-to-day stability.
• Cleaner Project Structure: We've moved the settings and internal files out of your Assets/Resources folder into a dedicated Plugins directory, keeping your project organized.
• Smarter Scripting: When an AI agent modifies your scene via a script, the scene is now automatically marked as "dirty" (unsaved), so you won't accidentally lose changes when closing Unity.
• Better Feedback from AI: Tool outputs now clearly state whether Unity is in Edit Mode or Play Mode, giving you and the AI agent better context for why certain operations might be unavailable.
• Safer Testing: Running tests through an agent is now safer. The server will automatically save your work before starting tests and restore your open scenes exactly how they were once the tests finish.

⚠️ Breaking Changes & Migration

1. Settings Asset Migration

The Unity settings asset has been moved to a developer-friendly location to avoid cluttering the Assets/Resources folder:

• Old Path: Assets/Resources/UnityCodeMcpServerSettings.asset
• New Path: Assets/Plugins/UnityCodeMcpServer/Editor/UnityCodeMcpServerSettings.asset
• Note: Users may need to re-configure custom ports or log levels in the new asset. Use Tools > UnityCodeMcpServer > Show or Create Settings to access it.

2. STDIO Bridge Configuration

The unity-code-mcp-stdio bridge now automatically discovers the Unity port from the project settings.

• Removed Parameters: --host and --port are no longer supported.
• Action: Update your MCP client (VS Code, Claude Desktop) configuration to remove these flags.
• Tip: Use Tools > UnityCodeMcpServer > STDIO > Print MCP configuration to console to view your ready-to-use configuration.

---

🚀 Key Improvements

🛠 Tools & Script Execution

• execute_csharp_script_in_unity_editor Enhancements:
  • Now uses ScriptExecutionService for more robust compilation and execution via Roslyn.
  • Automatically marks the active scene as dirty after execution in Edit Mode.
  • Improved output formatting with markdown sections for Result, Script, Logs, and Errors.
  • Added "Mode Indication" to tool outputs (e.g., "Unity Editor is in Edit Mode").
• read_unity_console_logs Enhancements:
  • New parameter max_entries to limit context window bloat.
  • Improved reliability when fetching logs via reflection.
• run_unity_tests Enhancements:
  • Fixed a bug where Both mode only ran EditMode tests.
  • Added automatic saving of dirty scenes before running tests.
  • Implemented scene state restoration: original scenes are restored after tests finish.
  • Block EditMode tests while the Editor is in Play Mode to prevent instability.
• get_unity_info Tool (New):
  • Returns Unity Editor project path and current server settings.
  • Useful for verifying server configuration and troubleshooting connectivity issues.

📝 Logging & Diagnostics

• LoopLogger: Consolidated internal logging system with configurable levels (Info, Debug, Warn, Error).
• LogCapture: Implemented a thread-safe log capture mechanism to redirect Unity's Debug.Log output back to the MCP tools during script execution.

🏗 Infrastructure & Testing

• Server Robustness:
  • Prevented automatic server startup when Unity is running in batch mode.
  • TCP Socket Management: Implemented the LingerState option (with LingerOption(true, 0)) to force the TCP socket to close immediately on shutdown. This prevents the socket from entering the TIME_WAIT state, ensuring the port is instantly available for a restart without "address already in use" errors—crucial for Unity domain reloads and developer iteration.
• Test Organization:
  • Moved EditMode tests to Assets/Tests/EditMode with updated namespaces.
  • Added initial PlayMode test infrastructure in Assets/Tests/PlayMode.
• Tool Descriptions: Greatly enhanced tool descriptions with "WHEN TO USE" and "CRITICAL DIRECTIVES" to guide AI agents better.

---

📦 Version History (Branch 0.1)

• 0.1.7-preview: Removed port/host parameters from bridge; finalized settings relocation.
• 0.1.6-preview: Refactored tool/resource paths; improved README instructions.
• 0.1.5-preview: Scene dirtying improvements; further tool description polish.
• 0.1.3-preview / 0.1.4-preview: Logging system refactor and LogCapture implementation.
• 0.1.2-preview: Initial ScriptExecutionService integration.
• 0.1.0-preview: Version bump and baseline for 0.1 features.