How to use Cursor with Unity

Short answer: open your Unity project's root folder in Cursor, keep the Unity Editor open on the same project, and let Cursor's agent edit C# scripts under Assets/. Unity recompiles, you read the Console, and you run tests. When you want the agent to see inside the Editor, install the free Unity CLI and run unity mcp configure cursor. You can try all of it on Cursor's Free plan. Everything below comes from Unity's docs and Cursor's docs, checked October 21, 2026.

What you are connecting

• Cursor. A code editor with an AI agent built in. It reads and edits the files in the folder you open, so it can write your C# scripts like any editor.
• The Unity CLI. A free command-line tool from Unity. With the Unity Pipeline package in your project it can drive a running Editor, and unity mcp runs an MCP server for agents. MCP (Model Context Protocol) is a standard way to give an agent tools inside another app. Unity's release notes say the server exposes the commands of a connected Editor as MCP tools over stdio. Docs: Use the Unity CLI.
• Unity skills. unity skill install cursor installs Unity's agent skills where Cursor can load them, so the agent follows Unity's own guidance instead of guessing.

Heads up if you read older tutorials: Unity has deprecated the MCP server inside the in-editor AI assistant package (com.unity.ai.assistant). Unity's docs say the Unity CLI replaces it, and name cursor as an example client for the migration command (Unity CLI as the replacement for the in-Editor MCP server).

What you need

• Unity 6.0 or newer. Unity says the CLI drives a running Editor from Unity 6.0 LTS on. Get it from unity.com/download via Unity Hub. Older Editors still work with the plain file edit loop.
• Cursor for macOS, Windows or Linux. The Free plan ($0) includes limited agent requests, which is enough to try this. Paid plans start at $8/mo (Plus, Grok models only), per Cursor pricing.
• Git, so you can undo a bad change with one command.
• For the Unity CLI: Windows 10 21H1 or newer, macOS 14 or newer, or Ubuntu 22.04 / RHEL 9 or newer, per Unity's CLI docs.

The realistic workflow (MCP optional)

1. Cursor edits C# directly under Assets/, plus test folders when you ask.
2. The Unity Editor stays open on the same project, so scripts recompile and errors show up in the Console.
3. You read the Console and paste errors back. With the Unity CLI connected, the agent can check the Editor itself.
4. You run tests with the Unity Test Framework, starting with Edit Mode tests.
5. You playtest. No agent can tell you if the jump feels good.

Setup, step by step

1. Create a Unity project and commit it

In Unity Hub, install a Unity 6 Editor and create a 2D or 3D project in its own folder. Open it once so Unity creates Assets/, ProjectSettings/ and the .meta files. Then run git init in that folder, add a .gitignore like this one (never ignore *.meta), and make a first commit:

# Unity generated
/[Ll]ibrary/
/[Tt]emp/
/[Oo]bj/
/[Bb]uild/
/[Bb]uilds/
/[Ll]ogs/
/[Uu]ser[Ss]ettings/
*.csproj
*.sln
*.user

2. Open the project in Cursor

Install Cursor, sign in, and use File, Open Folder on the project root, the folder that holds Assets/. Open the agent chat and ask it to explain the project layout. That is a safe first request that changes nothing.

3. Add an AGENTS.md

Cursor reads an AGENTS.md file in your project root as plain instructions for the agent (Cursor rules and AGENTS.md). For more control it also supports .mdc rule files in .cursor/rules. This is an example, so edit it for your project:

# Unity project notes for the agent

- Engine: Unity 6 (edit this to match your exact version, e.g. 6000.0).
- Scripts live under Assets/Scripts/. Prefer small MonoBehaviour components.
- Prefer editing .cs files. Do not hand edit .unity scene or .prefab YAML unless asked.
- After script edits, wait for the Editor to recompile, then check the Console for errors.
- Tests: Edit Mode tests live under Assets/Tests/EditMode/.
- Never delete or rename .meta files. Commit .meta files with new assets.
- Ask before changing Project Settings, Packages/manifest.json or Input System bindings.

Your first tiny task

1. Ask the agent: Create Assets/Scripts/PlayerController.cs: a 2D Rigidbody2D player that moves with WASD or the arrow keys. Add a comment at the top explaining how to attach it.
2. Switch to the Unity Editor and wait for it to recompile. Create a Sprite or Capsule, add a Rigidbody2D, attach the script and press Play. If the Console shows errors, copy them into Cursor and ask it to fix them.
3. Ask: Add an Edit Mode test assembly under Assets/Tests/EditMode with one test for a plain C# helper, for example clamping move speed. Run it from the Test Runner window in the Editor.
4. Commit, then add one more feature: a coin, a score, a simple enemy. Repeat edit, Console, test, play, commit.

Prefer the terminal for tests? The Unity Test Framework runs Edit Mode tests in batch mode with Unity -batchmode -runTests -projectPath . -testPlatform EditMode -testResults TestResults.xml. Unity's manual says a project can't open in batch mode while the Editor has it open, so close the Editor first.

Optional: connect Cursor to the Editor with the Unity CLI

1. Install the Unity CLI. Unity's script for macOS or Linux is curl -fsSL https://unity.com/install.sh | bash (Windows PowerShell: irm https://unity.com/install.ps1 | iex). Then run unity --version. Unity Hub also updates the CLI, so you may already have it.
2. Open your project in the Editor, then from the project folder run unity pipeline install to add the Pipeline package. Let the Editor recompile.
3. Check the connection with unity status. It should report the Editor as reachable for your project.
4. Register the MCP server in Cursor: unity mcp configure cursor. Add --dry-run first to see the config path it would write. Unity says only the Unity entry is written and every other key in the file is kept. unity mcp configure --list shows every supported client and its status.
5. Install Unity's skills for Cursor: unity skill install cursor. Add --local to install into this project, which Unity says also copies the skill that ships with your project's Pipeline package.
6. Restart Cursor, open Customize in the sidebar, and make sure the Unity server is turned on. Then ask: Read the Unity Console and summarize any errors. Cursor asks you to approve each MCP tool call by default.

Writing the entry by hand: Cursor reads .cursor/mcp.json in your project or ~/.cursor/mcp.json for every project, and runs local servers from a command and args (MCP in Cursor). unity mcp is a stdio server, so an entry looks like this. This is our example, so prefer what unity mcp configure cursor --dry-run shows:

{
  "mcpServers": {
    "unity": {
      "command": "unity",
      "args": ["mcp"]
    }
  }
}

Two Editors open? Unity's CLI release notes say unity mcp reads UNITY_PROJECT_PATH (or --project-path) to pick which project's Editor it talks to.

Common errors and fixes

• unity: command not found. Unity's docs say to reopen your terminal or add the install folder to your PATH. If Cursor was open during the install, restart it so it sees the new PATH.
• unity status cannot reach the Editor. Open the project in the Editor, run unity pipeline install in that folder, and wait for the recompile to finish.
• The agent's terminal cannot reach the Editor, but your own terminal can. Unity's release notes say the CLI now prints a hint about the agent's sandbox when this happens inside Cursor's agent. Approve the command when Cursor asks, or use the MCP server instead of raw CLI calls.
• The Unity server does not show up in Cursor. Check that Cursor has the project root open if the entry is in .cursor/mcp.json, then open the Output panel and pick MCP Logs.
• "Missing script" or broken references. A .meta file was deleted or not committed. Restore it from git. Never let the agent "clean up" meta files.
• Requests run out fast on Free. Ask for one small change at a time and turn off MCP servers you are not using, since every server adds context.

Cursor, Claude Code or Codex for Unity?

All three can use the same Unity CLI MCP server. Unity's official agent plugin is published for Claude Code and Codex, so they get a slightly smoother Unity setup. Cursor makes sense if you want a normal code editor where you watch every change, and a free plan to start. See How to use Claude Code with Unity, How to use Codex with Unity and Claude Code vs Codex vs Cursor for game dev.

Sources

• Use the Unity CLI (Unity docs)
• Unity CLI as the replacement for the in-Editor MCP server (Unity docs)
• Unity CLI release notes
• Unity's AI tools and FAQ
• Unity Test Framework command-line reference 1.4
• Model Context Protocol in Cursor (Cursor docs)
• Rules and AGENTS.md (Cursor docs)
• Agent Skills in Cursor (Cursor docs)
• Cursor pricing

All checked October 21, 2026. Plans change often, so check current pricing before you pay. Prices are in USD and exclude tax.

Related

Using Unreal instead? Follow How to use Cursor with Unreal Engine. Still choosing an engine? Read Godot vs Unity for beginners. See also our Cursor and Unity tool pages.

FAQ

Does Cursor work with Unity officially?

Yes, through the free Unity CLI. Unity's docs list cursor as a client for unity mcp configure, which registers the Unity CLI's MCP server in Cursor in one step, and its release notes say unity skill install for Cursor installs a real Agent Skills directory. Unity's official agent plugin is published for Claude Code, Codex, Grok and Antigravity, and we did not find a unity setup command for Cursor (checked October 21, 2026).

Can I do this for free?

You can start for $0. Cursor's Free plan includes limited agent requests, Unity Personal is free to download, and Unity says its CLI and MCP server are free to use. Cursor's paid plans start at $8/mo (Plus, Grok models only). Checked on cursor.com/pricing and Unity's docs, October 21, 2026.

Do I need MCP at all?

No. The core loop works without it: Cursor edits C# under Assets/, the Unity Editor recompiles, you read the Console and paste errors back, then run tests. MCP is an optional extra that lets the agent read the Console and drive the Editor itself.

Where does Cursor keep the Unity MCP entry?

Cursor reads MCP servers from .cursor/mcp.json in your project and from ~/.cursor/mcp.json in your home folder. Run unity mcp configure cursor --dry-run first to see exactly which file it would write. Unity says only the Unity entry is written and every other key in the file is kept.

Is Unity's in-Editor MCP server still the way to connect?

No. Unity's docs say the MCP server inside the in-editor AI assistant package (com.unity.ai.assistant) is deprecated and point you to the Unity CLI instead. Third-party MCP packages from GitHub are not affected.

Which Unity version do I need?

Unity 6.0 LTS or later for the Unity CLI to drive a running Editor. Older Editors still work with the plain file edit loop.