UVCS MCP
Provides tools for working with Unity Version Control / Plastic SCM workspaces through the local cm CLI, including status inspection, pending changes, branches, labels, locks, diffs, file history, checkins, checkouts, and guarded merge workflows. It does not control the Unity Editor.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@UVCS MCP what pending changes do I have in my workspace?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
UVCS MCP - Unity Version Control / Plastic SCM MCP Server

Safe MCP server for Plastic SCM, Unity Version Control, and Unity DevOps Version Control source-control workspaces (cm 10.0.16.6656+, including 11.x).
UVCS MCP connects AI IDEs and coding agents to the local cm CLI through a fixed allowlist of documented SCM commands. It helps agents inspect source-control workspace state, prepare changes, create branches and labels, run guarded checkins, and perform merges without arbitrary shell access.
Current release: 1.4.1. Supported cm clients: 10.0.16.6656 and newer, including Unity Version Control / Unity DevOps Version Control 11.x.
Requirements
Node.js 22 or newer (tested on 22, 24, and 26);
an existing Plastic SCM / Unity Version Control workspace;
the
cmCLI.initfinds it onPATHor in the standard install folders and writes its absolute path; otherwise pass--cm=<path>;a logged-in
cmclient with access to the workspace server.
Related MCP server: MCPort
Not a Unity Editor MCP
UVCS MCP is not a Unity Editor automation server. It does not control scenes, GameObjects, Play Mode, Unity packages, editor windows, builds, or runtime objects.
It works with the Plastic SCM / Unity Version Control cm CLI and focuses on source-control workflows: status, pending changes, branches, labels, checkins, locks, diffs, and merges.
Production Quick Start
For one workspace, start with the guarded profile:
npx -y @proanima/uvcs-mcp@1.4.1 init \
--client=cursor,codex \
--workspace="D:/Repositories/YourWorkspace" \
--safety=guarded \
--print-configThe preview shows only the uvcs entries, the target files, and whether each file would be created, merged, or left unchanged. Project files such as .cursor/mcp.json go into the workspace folder; pass --project-dir=<folder> to put them elsewhere. Remove --print-config to apply it, then validate the result:
npx -y @proanima/uvcs-mcp@1.4.1 doctor \
--workspace="D:/Repositories/YourWorkspace"Restart the MCP client, then call:
uvcs_setup_status
uvcs_workspace_status
uvcs_style_setup_checkUse readonly when inspection is sufficient. Use standard only for trusted or disposable workspaces where repository identity pinning is intentionally not required.
Configure the MCP client to auto-approve only read-only tools and to ask you before every *_confirm tool. See Clients.
AI-Assisted Install
Ask your AI IDE to install this MCP server from the GitHub repository URL.
For example:
Install this MCP server from https://github.com/ProAnima/unity-version-control-mcp, configure it for my Plastic SCM / Unity Version Control source-control workspace, and run uvcs_doctor.Install From a Clone
Use a clone only when client configuration should run that checkout instead of the npm package:
git clone https://github.com/ProAnima/unity-version-control-mcp.git uvcs-mcp
cd uvcs-mcp
npm ci
node src/cli.js init-local --client=cursor --workspace="D:/Repositories/YourWorkspace"Always pass --workspace (or --project-dir): project files are written into the workspace folder, and init refuses to write them into the uvcs-mcp folder itself. Preview first with --print-config.
Restart your MCP client, then ask it to run:
uvcs_doctor
uvcs_workspace_statusManual Setup By OS
Windows:
npx -y @proanima/uvcs-mcp@1.4.1 init --client=cursor --workspace="D:\Repositories\YourWorkspace"macOS:
npx -y @proanima/uvcs-mcp@1.4.1 init --client=cursor --workspace="$HOME/Repositories/YourWorkspace"Linux:
npx -y @proanima/uvcs-mcp@1.4.1 init --client=cursor --workspace="$HOME/Repositories/YourWorkspace"Replace cursor with your client, or list several separated by commas. If cm is not found, add --cm=/path/to/cm. On macOS this matters for GUI clients, which do not inherit the shell PATH; init writes the absolute cm path as UVCS_CM_PATH for that reason.
init validates every target before writing. A malformed or JSONC config aborts the run with nothing written, unless --skip-invalid is passed, which skips that client and prints the entry to add by hand. Changed files are backed up as <file>.<YYYYMMDDHHmmss>.bak; unchanged files are not rewritten. Run uvcs-mcp init --help for every option.
Manual MCP Block
{
"command": "npx",
"args": ["-y", "@proanima/uvcs-mcp@1.4.1"],
"env": {
"UVCS_WORKSPACE": "D:/Repositories/YourWorkspace",
"UVCS_MCP_MODE": "readonly"
}
}On native Windows npx is the npx.cmd shim. Claude Code, Claude Desktop, Cursor, Codex 0.59+, Kiro, and OpenCode resolve it themselves. For Antigravity and Windsurf / Devin Desktop, or if a client reports spawn npx ENOENT, use "command": "cmd" with "args": ["/c", "npx", "-y", "@proanima/uvcs-mcp@1.4.1"]. See Clients.
Every environment variable is described in Configuration.
MCP Registry
The server is listed in the official MCP Registry as io.github.ProAnima/uvcs-mcp. Clients and directories that read the registry can install it from there; it still needs a local cm CLI and a workspace path (UVCS_WORKSPACE).
Supported Clients
Cursor (project and global)
Codex
Claude Desktop
Claude Code (project
.mcp.json;initalso prints the equivalentclaude mcp add --scope usercommand)OpenCode (project and global)
Antigravity (project and global)
Kiro (project and global)
Windsurf / Devin Desktop
Zed (template only)
See Clients for file locations.
Safety Model
Default mode is
readonly; an unrecognizedUVCS_MCP_MODEalso meansreadonly.Protocol handling is provided by the official MCP TypeScript SDK.
Tool input is validated server-side with strict schemas.
Write tools require
UVCS_MCP_MODE=standard.Every write uses
*_preparefollowed by the matching*_confirm, and tools carry MCP annotations so clients can auto-approve reads and require approval for writes.Checkin takes all tracked pending changes, or only the given
paths; a path-scoped checkin adds the.metapartner of every selected Unity asset and refuses assets whose.metais still private.Merges with conflicts are refused at prepare and again at confirm, so
uvcs_mergedoes not start a merge that the preview reports as conflicting.Item paths, branch names, and label names that
cmwould read as options (leading-) are rejected, and item paths cannot contain the wildcards*or?.Write confirmations are serialized per workspace and across MCP processes, and switch, merge, update, undo, checkout, release checkout, and checkin revalidate workspace state after prepare.
cmruns without a shell and with stdin closed, under separate read and write timeouts and an output limit.Repository delete, repository rename, arbitrary
cm, arbitrary shell execution, and rawcm apistartup are not exposed.Optional JSONL audit logging is available with
UVCS_AUDIT_LOG=/path/to/uvcs-mcp-audit.jsonl.
Tools
uvcs_doctoruvcs_policy_statusuvcs_setup_statusuvcs_workspace_statusuvcs_pending_changesuvcs_branch_infouvcs_locksuvcs_checkout_prepare/uvcs_checkout_confirmuvcs_release_checkout_prepare/uvcs_release_checkout_confirmuvcs_unity_meta_diagnosticsuvcs_style_rulesuvcs_style_setup_checkuvcs_style_init_prepare/uvcs_style_init_confirmuvcs_name_previewuvcs_release_planuvcs_diff_fileuvcs_changeset_diffuvcs_revision_diffuvcs_file_historyuvcs_annotateuvcs_branch_listuvcs_label_listuvcs_merge_previewuvcs_cleanup_candidatesuvcs_branch_safety_reportuvcs_update_workspace_prepare/uvcs_update_workspace_confirmuvcs_changeset_analyticsuvcs_add_prepare/uvcs_add_confirmuvcs_undo_prepare/uvcs_undo_confirmuvcs_branch_create_prepare/uvcs_branch_create_confirmuvcs_label_create_prepare/uvcs_label_create_confirmuvcs_switch_workspace_prepare/uvcs_switch_workspace_confirmuvcs_merge_prepare/uvcs_merge_confirmuvcs_checkin_prepare/uvcs_checkin_confirm
History, Review, and Merge Preview
Read-only tools answer "what changed" questions in every safety profile:
uvcs_changeset_difflists items added, changed, moved, or deleted in a changeset (cs:123), a branch (/main/task), a shelve, or between two changesets or labels, and flags Unity assets added, moved, or deleted without their.meta(and the reverse).uvcs_revision_diffreturns a unified line diff of one file for a changeset, between two revisions, or against the workspace copy.uvcs_file_historyanduvcs_annotateshow who changed a file or a line, and when.uvcs_branch_listanduvcs_label_listfind branches and labels by name, owner, date, parent, or branch.uvcs_merge_previewreports what a merge would bring and which items conflict, into the workspace or, withdestination, into any branch on the server, without merging.
Checkin by Path and Exclusive Checkout
uvcs_checkin_prepareacceptspathsto check in only the user's files or folders. Every selected Unity asset brings its.metafile along, new parent folders that the change needs are listed asdependencies, and the token is invalidated if a selected file is edited again before confirm.uvcs_checkout_preparechecks files out before editing. When the server has a lock rule for them (lock.conf), this takes the exclusive lock that protects scenes, prefabs, and other binary assets; files locked by someone else are refused.uvcs_release_checkout_preparereleases checkouts of files whose content did not change. Modified files keep their checkout and their edits until they are checked in.uvcs_locksacceptspathsand ascope(all,user,workspace).
Agent Skill
The package ships an agent skill (SKILL.md) that teaches Claude Code, Codex, Cursor, OpenCode, Gemini CLI, and other SKILL.md agents when and how to use these tools, including the prepare/confirm workflow and Unity .meta rules:
npx -y @proanima/uvcs-mcp@1.4.1 skill install --agent=claude,agentsSee Agent Skill for every agent, project-scope installs, and the marketplace ZIP.
Multiple Workspaces
Use a fleet manifest to configure one MCP server for up to 50 named workspaces:
npx -y @proanima/uvcs-mcp@1.4.1 init --manifest=workspaces.json --client=cursor,codex --print-configStart from templates/fleet/workspaces.example.json. See Multi-Workspace and Fleet Work for safety profiles and the recommended prepare-all/confirm-each workflow.
In fleet mode every tool call requires an explicit workspace selector. Use --fleet-layout=isolated only when you prefer one MCP process per workspace.
Validate every configured workspace before restarting the client:
npx -y @proanima/uvcs-mcp@1.4.1 doctor --manifest=workspaces.jsonFor mass work, inspect every target first, prepare all writes, present one combined plan, and confirm each workspace independently. Cross-repository operations are not atomic.
Development
npm ci
npm test
npm run lint
npm run check
npm run audit:prod
npm run release:check
npm run smoke:fake
npm run smoke:fleet
npm run smoke:pack
npm run pack:skillRun the real Plastic SCM smoke test against a disposable or safe workspace:
npm run smoke:plastic -- "D:/Repositories/YourWorkspace"The smoke test creates temporary branches, labels, checkins, and a merge through MCP tools.
Project Support
Use GitHub Issues for reproducible bugs, client setup problems, and compatibility reports.
Use feature requests for new SCM workflows or MCP tools.
Do not include secrets, access tokens, private server credentials, or full proprietary logs in public issues.
For security reports, see Security Policy.
Documentation
Maintainer
Ian Panaev, ProAnimaStudio, 2026. Contact: proanimastudio@gmail.com.
Available Tools
45 toolsuvcs_add_confirmA
Add a path to Plastic SCM / UVCS version control recursively. For Unity assets also add the matching .meta file. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_add_prepareARead-onlyIdempotent
Add a path to Plastic SCM / UVCS version control recursively. For Unity assets also add the matching .meta file. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: itemPath (required).
uvcs_annotateARead-onlyIdempotent
Show who last changed each line of a text file and in which changeset (blame). Binary files cannot be annotated. Read-only.
Inputs: filePath (required), maxLines, revision, startLine.
uvcs_branch_create_confirmA
Create a Plastic SCM / UVCS branch from a changeset or label. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_branch_create_prepareARead-onlyIdempotent
Create a Plastic SCM / UVCS branch from a changeset or label. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: branch (required), comment, fromLabel, fromChangeset.
uvcs_branch_infoBRead-onlyIdempotent
Return current branch information.
Inputs: no named parameters.
uvcs_branch_listARead-onlyIdempotent
List branches, newest first, with owner, parent branch, head changeset, and comment. Read-only.
Inputs: owner, since, parent, nameLike, +1 more.
uvcs_branch_safety_reportARead-onlyIdempotent
Read-only helper that reports current branch, pending changes, and recent changesets before risky branch, merge, or cleanup work.
Inputs: branch, recentChangesets.
uvcs_changeset_analyticsCRead-onlyIdempotent
Analyze changesets over an optional date, branch, owner, or comment filter. Read-only.
Inputs: owner, since, until, branch, +2 more.
uvcs_changeset_diffARead-onlyIdempotent
List the items added, changed, moved, or deleted in a changeset, label, shelve, or branch, or between two changesets/labels, with Unity .meta pairing warnings. Read-only.
Inputs: source (required), maxItems, compareTo.
uvcs_checkin_confirmA
Run a prepared checkin (all tracked pending changes, or the selected paths). Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_checkin_prepareARead-onlyIdempotent
Prepare a checkin and return a short-lived confirmation token. Without paths it takes ALL tracked pending changes in the workspace; with paths only the changes at or below those paths, plus the Unity .meta partner of every selected asset. Private files are never included, except a new parent folder that a selected item needs (listed in dependencies). Review the returned changes with the user before confirming.
Inputs: message (required), paths.
uvcs_checkout_confirmA
Check out files before editing them. When the server has a lock rule for them (lock.conf), this takes the exclusive lock so nobody else can check them out or check in changes to them, which is how teams protect scenes, prefabs, and other binary assets. Files locked by someone else are refused. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_checkout_prepareARead-onlyIdempotent
Check out files before editing them. When the server has a lock rule for them (lock.conf), this takes the exclusive lock so nobody else can check them out or check in changes to them, which is how teams protect scenes, prefabs, and other binary assets. Files locked by someone else are refused. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: paths (required).
uvcs_cleanup_candidatesARead-onlyIdempotent
Read-only helper that lists temporary/agent branch cleanup candidates for manual review. It never deletes branches or changesets.
Inputs: patterns, maxResults.
uvcs_diff_fileARead-onlyIdempotent
Return a unified line diff of one pending file: the revision loaded in the workspace against the file on disk. Output longer than 200000 characters is truncated. Read-only.
Inputs: filePath (required), context.
uvcs_doctorBRead-onlyIdempotent
Check cm, workspace, and UVCS MCP configuration.
Inputs: no named parameters.
uvcs_file_historyARead-onlyIdempotent
List the revisions of a file or directory, newest first, with changeset, branch, date, owner, and comment. Dates use the cm client locale format (cm history has no date format option). Read-only.
Inputs: filePath (required), maxResults.
uvcs_label_create_confirmA
Create a Plastic SCM / UVCS label on a changeset. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_label_create_prepareBRead-onlyIdempotent
Create a Plastic SCM / UVCS label on a changeset. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: label (required), target (required), comment.
uvcs_label_listBRead-onlyIdempotent
List labels, newest first, with labeled changeset, branch, owner, and comment. Read-only.
Inputs: owner, since, branch, nameLike, +1 more.
uvcs_locksARead-onlyIdempotent
List exclusive locks (cm lock list). Without paths, the list covers every repository on the server; pass paths to check specific files in this workspace.
Inputs: paths, scope.
uvcs_merge_confirmADestructive
Merge a branch/changeset/label into the current workspace branch. Refused while tracked pending changes exist or when the merge has conflicts (resolve those in the UVCS client); the merge result stays pending until a checkin. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_merge_prepareARead-onlyIdempotent
Merge a branch/changeset/label into the current workspace branch. Refused while tracked pending changes exist or when the merge has conflicts (resolve those in the UVCS client); the merge result stays pending until a checkin. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: source (required), comment.
uvcs_merge_previewARead-onlyIdempotent
Preview a merge without changing anything: files that would be taken from the source, items added/moved/deleted, and conflicts. Without destination the target is the workspace branch; with destination the preview is computed on the server for that branch. Read-only.
Inputs: source (required), maxItems, destination.
uvcs_name_previewARead-onlyIdempotent
Preview a branch name or checkin message from workspace style rules.
Inputs: kind (required), type (required), title, summary, +1 more.
uvcs_pending_changesBRead-onlyIdempotent
Return full pending changes from cm status.
Inputs: no named parameters.
uvcs_policy_statusARead-onlyIdempotent
Show the effective workspace identity, safety profile, allowlists, write limits, and mass-work guidance.
Inputs: no named parameters.
uvcs_release_checkout_confirmA
Release checkouts (and their locks) of files whose content did not change. Modified files keep their checkout and their edits; check those in or undo them. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_release_checkout_prepareARead-onlyIdempotent
Release checkouts (and their locks) of files whose content did not change. Modified files keep their checkout and their edits; check those in or undo them. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: paths (required).
uvcs_release_planBRead-onlyIdempotent
Plan a major, minor, or patch release branch, label, and comments from workspace style rules. Read-only.
Inputs: projectName, releaseType, currentVersion, releaseVersion.
uvcs_revision_diffARead-onlyIdempotent
Return a unified line diff of one text file between two revisions, or between a revision and the workspace copy. Pass changeset to see what that changeset changed in the file. Output longer than 200000 characters is truncated. Read-only.
Inputs: filePath (required), to, from, context, +1 more.
uvcs_setup_statusBRead-onlyIdempotent
Show safety policy and branch/checkin/release naming setup in one place.
Inputs: no named parameters.
uvcs_style_init_confirmA
Create .uvcs-mcp/style.json with branch naming, checkin message, and release conventions. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_style_init_prepareBRead-onlyIdempotent
Create .uvcs-mcp/style.json with branch naming, checkin message, and release conventions. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: preset, overwrite, baseBranch, versionFile, +1 more.
uvcs_style_rulesARead-onlyIdempotent
Return workspace naming and release style rules.
Inputs: no named parameters.
uvcs_style_setup_checkARead-onlyIdempotent
Check whether workspace naming/checkin/release style rules exist. If missing, guide the model to ask the user to create them before branch work.
Inputs: no named parameters.
uvcs_switch_workspace_confirmADestructive
Switch the workspace to a branch, changeset, or label. Refused while tracked pending changes exist. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_switch_workspace_prepareARead-onlyIdempotent
Switch the workspace to a branch, changeset, or label. Refused while tracked pending changes exist. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: target (required).
uvcs_undo_confirmADestructive
Irreversibly undo pending changes for one path inside the selected workspace. Workspace-root undo is forbidden. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_undo_prepareBRead-onlyIdempotent
Irreversibly undo pending changes for one path inside the selected workspace. Workspace-root undo is forbidden. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: itemPath (required), recursive.
uvcs_unity_meta_diagnosticsARead-onlyIdempotent
Detect common Unity asset/.meta mismatches in the workspace.
Inputs: no named parameters.
uvcs_update_workspace_confirmADestructive
Update the workspace to the latest changeset of its branch. Local edits to files changed upstream can produce merge conflicts. Requires prepare/confirm. Confirms and executes a prepared operation. Call only after the user has reviewed the prepared payload and explicitly approved this exact operation.
Inputs: token (required), confirmPhrase (required).
uvcs_update_workspace_prepareARead-onlyIdempotent
Update the workspace to the latest changeset of its branch. Local edits to files changed upstream can produce merge conflicts. Requires prepare/confirm. Returns a short-lived confirmation token.
Inputs: no named parameters.
uvcs_workspace_statusBRead-onlyIdempotent
Return concise workspace status.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 45 tools
Mutating operations are split into prepare/confirm pairs with descriptions that clarify the workflow, but the large surface creates some overlap among status/diagnostic tools such as doctor, policy_status, setup_status, workspace_status, and branch_info. Read-only previews and diffs are mostly distinct, but several tools require careful reading to choose correctly.
All tools use the uvcs_ prefix and snake_case, with a predictable _prepare/_confirm suffix for mutating operation pairs. A few read-only tools use noun-style names rather than strict verb_noun, but the pattern is still mostly consistent and readable.
45 tools is well above the 25+ threshold for a heavy surface, even accounting for the many prepare/confirm pairs. The set is comprehensive, but the sheer number of tools increases selection cost and makes the server feel over-scoped.
Core version-control workflows are covered: status, pending changes, branch/label creation and listing, checkout, checkin, merge, update, diff, history, annotate, and workspace switching. However, notable lifecycle gaps remain, including branch/label deletion or modification, shelve/unshelve, rollback/revert changeset, and in-client conflict resolution is explicitly out of scope.
Maintenance
Related MCP Connectors
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Read-only AI coding tools for change verification, release readiness, capacity, and guidance.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables AI clients to inspect and carefully edit a bounded local workspace via stdio, with a read-only default, conflict-safe updates, and no network listener or telemetry.102Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI clients to safely read, search, understand, and edit local project code and files, with Git inspection, code indexing, and controlled command execution within permissioned workspaces.8 npm6MIT
- AlicenseAqualityBmaintenanceEnables MCP-compatible AI clients to securely access explicitly authorized local project files and run approved development commands with bounded execution and audit logging.1MIT
- AlicenseNot gradedqualityCmaintenanceEnables remote AI agents to read, patch, and (opt-in) execute commands in a local workspace, with all actions approved locally and fully audited.2MIT