Linkedsword

A Roblox Studio MCP server and plugin. Lets you drive Studio from an MCP client (Claude Code, Cursor, VS Code, etc.) — read the data model, edit scripts with a diff review step, run playtests, manage assets.

Features

• Diff-reviewed script editing. Edits stage as hunks inside the plugin widget. Accept or reject each one before it touches the source.

• Planning Mode. Multi-step plans with DataModel checkpoints. Snapshot before a risky step, revert if it goes sideways.

• Playtest automation. Start/stop play sessions, simulate keyboard/mouse, run end-to-end scenarios with structured pass/fail verdicts.

• Asset pipeline. Upload Decals/Audio/Models/Meshes via Open Cloud or a ROBLOSECURITY cookie; search the Creator Store; resolve thumbnails.

• Inspector build. A separate read-only .rbxmx variant for sessions where you don't want any write surface.

• Stable instance handles. ls://<uuid> handles that survive renames and reparents.

• Multi-instance Studio. Connect to multiple Studio windows and route tools to any of them.

93 tools across navigation, search, scripts, instances, playtests, plans, assets, and terrain.

Install

Requires Node.js 18+ and Roblox Studio.

# Auto-detect installed MCP clients and add Linkedsword
npx linkedsword-mcp install

# Build and install the Studio plugin
npx linkedsword-mcp install --plugin

Or wire it into your MCP client by hand:

{
  "mcpServers": {
    "linkedsword": {
      "command": "npx",
      "args": ["-y", "linkedsword-mcp"]
    }
  }
}

In Roblox Studio enable File → Game Settings → Security → Allow HTTP Requests (per-place), then click the Linkedsword toolbar button to connect.

Asset uploads

Drop credentials into ~/.linkedsword/auth.json, or use the CLI:

# Open Cloud API key (recommended; supports all asset types)
npx linkedsword-mcp auth set --api-key=<key> --user-id=<creator-id>

# Or ROBLOSECURITY cookie (Decal uploads only)
npx linkedsword-mcp auth set --cookie=<cookie>

The file is written with mode 0600. auth show prints a masked summary.

Architecture

MCP client  ──stdio──>  Linkedsword server  ──HTTP (127.0.0.1:3003)──>  Studio plugin

The server registers MCP tools and runs an Express bridge. The plugin long-polls the bridge for work, executes it against the live DataModel, and posts results back. Script edits go through a diff engine that stages hunks in a pop-out window for review.

Build from source

git clone https://github.com/yannyhl/linkedsword-mcp.git
cd linkedsword-mcp
npm install

# Server
npx tsup packages/server/src/index.ts --format cjs --out-dir packages/server/dist --clean

# Plugin (normal + inspector-only variants)
node packages/plugin/build-rbxmx.js
node packages/plugin/build-rbxmx.js --inspector

# Deploy
cp packages/plugin/Linkedsword.rbxmx ~/Documents/Roblox/Plugins/

Known limitations

• Plugin sandbox doesn't expose viewport pixels — capture_screenshot returns camera metadata only, not a real image.

• Heartbeat can drop on rapid parallel calls. Retry once if you see a timeout.

• Procedural Models aren't implemented yet (Roblox added the instance type in April 2026; tool support is on the roadmap).

License

MIT