Skip to main content
Glama

UVCS MCP - Unity Version Control / Plastic SCM MCP Server

UVCS MCP header

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 cm CLI. init finds it on PATH or in the standard install folders and writes its absolute path; otherwise pass --cm=<path>;

  • a logged-in cm client 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-config

The 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_check

Use 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_status

Manual 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; init also prints the equivalent claude mcp add --scope user command)

  • 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 unrecognized UVCS_MCP_MODE also means readonly.

  • 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 *_prepare followed 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 .meta partner of every selected Unity asset and refuses assets whose .meta is still private.

  • Merges with conflicts are refused at prepare and again at confirm, so uvcs_merge does not start a merge that the preview reports as conflicting.

  • Item paths, branch names, and label names that cm would 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.

  • cm runs 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 raw cm api startup are not exposed.

  • Optional JSONL audit logging is available with UVCS_AUDIT_LOG=/path/to/uvcs-mcp-audit.jsonl.

Tools

  • uvcs_doctor

  • uvcs_policy_status

  • uvcs_setup_status

  • uvcs_workspace_status

  • uvcs_pending_changes

  • uvcs_branch_info

  • uvcs_locks

  • uvcs_checkout_prepare / uvcs_checkout_confirm

  • uvcs_release_checkout_prepare / uvcs_release_checkout_confirm

  • uvcs_unity_meta_diagnostics

  • uvcs_style_rules

  • uvcs_style_setup_check

  • uvcs_style_init_prepare / uvcs_style_init_confirm

  • uvcs_name_preview

  • uvcs_release_plan

  • uvcs_diff_file

  • uvcs_changeset_diff

  • uvcs_revision_diff

  • uvcs_file_history

  • uvcs_annotate

  • uvcs_branch_list

  • uvcs_label_list

  • uvcs_merge_preview

  • uvcs_cleanup_candidates

  • uvcs_branch_safety_report

  • uvcs_update_workspace_prepare / uvcs_update_workspace_confirm

  • uvcs_changeset_analytics

  • uvcs_add_prepare / uvcs_add_confirm

  • uvcs_undo_prepare / uvcs_undo_confirm

  • uvcs_branch_create_prepare / uvcs_branch_create_confirm

  • uvcs_label_create_prepare / uvcs_label_create_confirm

  • uvcs_switch_workspace_prepare / uvcs_switch_workspace_confirm

  • uvcs_merge_prepare / uvcs_merge_confirm

  • uvcs_checkin_prepare / uvcs_checkin_confirm

History, Review, and Merge Preview

Read-only tools answer "what changed" questions in every safety profile:

  • uvcs_changeset_diff lists 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_diff returns a unified line diff of one file for a changeset, between two revisions, or against the workspace copy.

  • uvcs_file_history and uvcs_annotate show who changed a file or a line, and when.

  • uvcs_branch_list and uvcs_label_list find branches and labels by name, owner, date, parent, or branch.

  • uvcs_merge_preview reports what a merge would bring and which items conflict, into the workspace or, with destination, into any branch on the server, without merging.

Checkin by Path and Exclusive Checkout

  • uvcs_checkin_prepare accepts paths to check in only the user's files or folders. Every selected Unity asset brings its .meta file along, new parent folders that the change needs are listed as dependencies, and the token is invalidated if a selected file is edited again before confirm.

  • uvcs_checkout_prepare checks 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_prepare releases checkouts of files whose content did not change. Modified files keep their checkout and their edits until they are checked in.

  • uvcs_locks accepts paths and a scope (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,agents

See 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-config

Start 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.json

For 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:skill

Run 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 tools
uvcs_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_prepareA
Read-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_annotateA
Read-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_prepareA
Read-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_infoB
Read-onlyIdempotent

Return current branch information.

Inputs: no named parameters.

uvcs_branch_listA
Read-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_reportA
Read-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_analyticsC
Read-onlyIdempotent

Analyze changesets over an optional date, branch, owner, or comment filter. Read-only.

Inputs: owner, since, until, branch, +2 more.

uvcs_changeset_diffA
Read-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_prepareA
Read-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_prepareA
Read-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_candidatesA
Read-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_fileA
Read-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_doctorB
Read-onlyIdempotent

Check cm, workspace, and UVCS MCP configuration.

Inputs: no named parameters.

uvcs_file_historyA
Read-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_prepareB
Read-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_listB
Read-onlyIdempotent

List labels, newest first, with labeled changeset, branch, owner, and comment. Read-only.

Inputs: owner, since, branch, nameLike, +1 more.

uvcs_locksA
Read-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_confirmA
Destructive

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_prepareA
Read-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_previewA
Read-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_previewA
Read-onlyIdempotent

Preview a branch name or checkin message from workspace style rules.

Inputs: kind (required), type (required), title, summary, +1 more.

uvcs_pending_changesB
Read-onlyIdempotent

Return full pending changes from cm status.

Inputs: no named parameters.

uvcs_policy_statusA
Read-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_prepareA
Read-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_planB
Read-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_diffA
Read-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_statusB
Read-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_prepareB
Read-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_rulesA
Read-onlyIdempotent

Return workspace naming and release style rules.

Inputs: no named parameters.

uvcs_style_setup_checkA
Read-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_confirmA
Destructive

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_prepareA
Read-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_confirmA
Destructive

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_prepareB
Read-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_diagnosticsA
Read-onlyIdempotent

Detect common Unity asset/.meta mismatches in the workspace.

Inputs: no named parameters.

uvcs_update_workspace_confirmA
Destructive

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_prepareA
Read-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_statusB
Read-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

    B3.2/5.0

    Scored across 45 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count2/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      10
      2
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables remote AI agents to read, patch, and (opt-in) execute commands in a local workspace, with all actions approved locally and fully audited.
      2
      MIT