OpenSimulator MCP Server

An MCP (Model Context Protocol) server that allows you to control OpenSimulator via console commands. Built with FastMCP.

Features

This MCP server exposes OpenSimulator console commands as tools, including:

General Commands: version, uptime, info, logging
Region Commands: create, delete, restart, change region context
User Commands: show users, alerts, kick, teleport, login control
Object Commands: show, delete, backup objects
Archive Commands: save/load OAR and IAR files
Terrain Commands: load, save, fill, elevate, lower terrain
Script Commands: start, stop, suspend, resume scripts
Estate Commands: show, reload, set estate properties
Stats Commands: show stats, monitor, queues, connections
Module Commands: list, load, unload modules
Land Commands: show, clear parcels
Asset Commands: cache status and management
Scene Commands: rotate, scale, translate scene
HyperGrid Commands: link/unlink regions
User Account Commands: create user, reset password, set user level

Prerequisites

OpenSimulator must be running with the REST console enabled. Start OpenSimulator with:
```
./OpenSim -console=rest
```

Configure the REST console in OpenSim.ini under [Network]:

[Network]
ConsoleUser = "admin"
ConsolePass = "password"
console_port = 0  ; Uses main HTTP port (default 9000)

Installation

# Clone the repository
cd /path/to/opensim-server-mcp

# Install with pip
pip install -e .

# Or with uv
uv pip install -e .

Configuration

The server is configured via environment variables:

Variable	Description	Default
`OPENSIM_PATH`	Path to OpenSimulator installation	`~/opensimulator`
`OPENSIM_CONSOLE_URL`	URL of the REST console	`http://127.0.0.1:9000`
`OPENSIM_CONSOLE_USER`	REST console username	(empty)
`OPENSIM_CONSOLE_PASS`	REST console password	(empty)

Usage

Running the Server

# Set environment variables
export OPENSIM_PATH=~/opensimulator
export OPENSIM_CONSOLE_URL=http://127.0.0.1:9000
export OPENSIM_CONSOLE_USER=admin
export OPENSIM_CONSOLE_PASS=secret

# Run the server
opensim-mcp

Configuring with Claude Desktop

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json on Linux):

{
  "mcpServers": {
    "opensim": {
      "command": "opensim-mcp",
      "env": {
        "OPENSIM_PATH": "/home/user/opensimulator",
        "OPENSIM_CONSOLE_URL": "http://127.0.0.1:9000",
        "OPENSIM_CONSOLE_USER": "admin",
        "OPENSIM_CONSOLE_PASS": "secret"
      }
    }
  }
}

Configuring with Windsurf/Cascade

Add to your MCP settings:

{
  "mcpServers": {
    "opensim": {
      "command": "opensim-mcp",
      "env": {
        "OPENSIM_PATH": "/home/rjodouin/opensimulator",
        "OPENSIM_CONSOLE_URL": "http://127.0.0.1:9000",
        "OPENSIM_CONSOLE_USER": "admin",
        "OPENSIM_CONSOLE_PASS": "secret"
      }
    }
  }
}

Available Tools (only three)

All OpenSimulator console commands are issued through three MCP tools:

get(command, args="") – for read-only/show/info queries.
set(command, args="") – for mutating/config/management actions.
run(command) – for any raw console command (escape hatch).

Examples by category

General Server Commands

These commands work on both simulator and ROBUST consoles.

Command	Description	Example
`command-script`	Run a command script containing console commands	`run("command-script myscript.txt")`
`quit` / `shutdown`	Shutdown the server	`set("quit")`
`show info`	Show server information (version and startup path)	`get("show info")`
`show uptime`	Show server startup time and uptime	`get("show uptime")`
`show version`	Show server version	`get("show version")`
`get log level`	Print the current console logging level	`get("get log level")`
`set log level`	Change the console logging level (e.g., off, debug)	`set("set log level", "debug")`
`help`	Get general command list or help on a specific command	`get("help")`, `get("help", "terrain")`

Debug Commands

Command	Description	Example
`debug http`	Turn on/off extra logging for HTTP request debugging	`set("debug http", "in 5")`
`debug threadpool level`	Turn on/off logging of activity in the main threadpool	`set("debug threadpool level", "1")`

Simulator Commands

General

Command	Description	Example
`change region`	Select region for subsequent commands; "root" selects all	`set("change region", "MyRegion")`
`debug packet`	Turn on packet debugging for viewer communications	`set("debug packet", "1")`
`emergency-monitoring`	Turn emergency debugging monitoring on/off	`set("emergency-monitoring", "on")`
`link-mapping`	Set local grid coordinate to map to remote hypergrid	`set("link-mapping", "1000 1000")`
`link-region`	Link a HyperGrid region	`set("link-region", "1000 1000 grid.example.com 8002 \"Remote\"")`
`unlink-region`	Unlink a hypergrid region	`set("unlink-region", "\"Remote Region\"")`
`modules list`	List modules	`get("modules list")`
`modules load`	Load a module	`set("modules load", "ModuleName")`
`modules unload`	Unload a module	`set("modules unload", "ModuleName")`
`monitor report`	Returns statistics about the current region/simulator	`get("monitor report")`
`set terrain heights`	Set terrain texture heights on a corner	`set("set terrain heights", "0 20 40")`
`set terrain texture`	Set terrain texture by number	`set("set terrain texture", "1 <uuid>")`
`set water height`	Set water height simulator-wide or per region	`set("set water height", "20")`
`show caps`	Show all registered capabilities URLs	`get("show caps")`
`show circuits`	Show agent circuit data	`get("show circuits")`
`show connections`	Show connections data	`get("show connections")`
`show http-handlers`	Show all registered HTTP handlers	`get("show http-handlers")`
`show hyperlinks`	List hypergrid linked regions	`get("show hyperlinks")`
`show modules`	Show module data	`get("show modules")`
`show pending-objects`	Show pending objects in viewer queues	`get("show pending-objects")`
`show pqueues`	Show priority queue data for each client	`get("show pqueues")`, `get("show pqueues", "full")`
`show queues`	Show queue data for agent connections	`get("show queues")`
`show threads`	Show persistent threads registered with the system	`get("show threads")`
`show throttles`	Show throttle data for each client connection	`get("show throttles")`, `get("show throttles", "full")`

Appearance Commands

Command	Description	Example
`appearance find`	Find which avatar uses a given asset as baked texture	`get("appearance find", "<uuid>")`
`appearance rebake`	Request user's viewer to rebake and reupload textures	`set("appearance rebake", "First Last")`
`appearance send`	Send appearance data for avatars to other viewers	`set("appearance send")`, `set("appearance send", "First Last")`
`appearance show`	Show appearance information for avatars	`get("appearance show")`, `get("appearance show", "First Last")`

Archive Commands

Command	Description	Example
`load iar`	Load user inventory archive	`set("load iar", "First Last /Inventory password archive.iar")`
`load oar`	Load OpenSimulator region archive (replaces region)	`set("load oar", "region.oar")`
`load xml`	Load region data from XML format (deprecated)	`set("load xml", "backup.xml")`
`load xml2`	Load region data from XML2 format	`set("load xml2", "backup.xml")`
`save iar`	Save user inventory archive	`set("save iar", "First Last /Inventory password archive.iar")`
`save oar`	Save current region to OpenSimulator archive	`set("save oar", "region.oar")`
`save prims xml2`	Save named prim to XML2	`set("save prims xml2", "\"My Prim\" prim.xml")`
`save xml`	Save prims to XML	`set("save xml", "backup.xml")`
`save xml2`	Save prims to XML2 format	`set("save xml2", "backup.xml")`

Asset Commands (fcache)

Command	Description	Example
`fcache assets`	Deep scan and cache all assets in all scenes	`set("fcache assets")`
`fcache clear`	Remove all assets in cache (file/memory optional)	`set("fcache clear")`, `set("fcache clear", "file")`
`fcache clearnegatives`	Clear negative cache entries if enabled	`set("fcache clearnegatives")`
`fcache expire`	Purge cached assets older than specified date	`set("fcache expire", "2024-01-01")`
`fcache status`	Display cache status	`get("fcache status")`
`j2k decode`	Do JPEG2000 decoding of an asset	`set("j2k decode", "<asset-uuid>")`

Config Commands

Command	Description	Example
`config get`	Get current configuration (section/key optional)	`get("config get")`, `get("config get", "Network")`
`config save`	Save current configuration to a file	`set("config save", "/path/to/config.ini")`
`config set`	Set a particular configuration value	`set("config set", "Section Key Value")`
`config show`	Synonym for config get	`get("config show")`

Land Commands

Command	Description	Example
`land show`	Show all parcels on the current region	`get("land show")`
`land clear`	Clear all parcels on the land	`set("land clear")`

Map Commands

Command	Description	Example
`export-map`	Save an image of the world map	`set("export-map", "worldmap.jpg")`
`generate map`	Regenerate and store map tile	`set("generate map")`

Object Commands

Command	Description	Example
`backup`	Persist unsaved object changes immediately	`set("backup")`
`delete object creator`	Delete scene objects by creator UUID	`set("delete object creator", "<creator-uuid>")`
`delete object id`	Delete scene object by UUID or localID	`set("delete object id", "<uuid-or-localID>")`
`delete object name`	Delete scene object by name (supports --regex)	`set("delete object name", "\"Object Name\"")`
`delete object outside`	Delete all objects outside region boundaries	`set("delete object outside")`
`delete object owner`	Delete scene objects by owner UUID	`set("delete object owner", "<owner-uuid>")`
`dump object id`	Dump object serialization to file for debugging	`set("dump object id", "<uuid>")`
`edit scale`	Change the scale of a named prim	`set("edit scale", "\"Object Name\" 1.0 1.0 1.0")`
`force update`	Force region to send all clients updates about objects	`set("force update")`
`show object id`	Show details of object by UUID or localID	`get("show object id", "<uuid-or-localID>")`
`show object name`	Show details of objects by name (supports --regex)	`get("show object name", "\"Object Name\"")`
`show part id`	Show details of object part by UUID or localID	`get("show part id", "<uuid-or-localID>")`
`show part name`	Show details of object parts by name (supports --regex)	`get("show part name", "\"Part Name\"")`

Estate Commands

Command	Description	Example
`estate create`	Create a new estate	`set("estate create", "<owner-uuid> \"Estate Name\"")`
`estate link region`	Attach a region to an estate	`set("estate link region", "<estate-id> <region-id>")`
`estate set name`	Rename an estate	`set("estate set name", "<estate-id> \"New Name\"")`
`estate set owner`	Change estate owner (by name or UUID)	`set("estate set owner", "<estate-id> First Last")`
`estate show`	Show estate name, ID, and owner for regions	`get("estate show")`
`reload estate`	Reload estate data	`set("reload estate")`

Region Commands

Command	Description	Example
`change region`	Select region for subsequent commands	`set("change region", "MyRegion")`
`create region`	Create a new region	`set("create region", "NewRegion Regions/NewRegion.ini")`
`delete-region`	Delete a region from disk	`set("delete-region", "OldRegion")`
`region get`	Show region parameters (name, UUID, location, etc.)	`get("region get")`
`region restart abort`	Abort a scheduled region restart	`set("region restart abort", "Restart cancelled")`
`region restart bluebox`	Schedule restart with dismissable bluebox notice	`set("region restart bluebox", "\"Msg\" 120 60 30")`
`region restart notice`	Schedule restart with transient notice	`set("region restart notice", "\"Msg\" 120 60 30")`
`region set`	Set region parameters (agent-limit, max-agent-limit)	`set("region set", "agent-limit 40")`
`remove-region`	Remove a region from the simulator	`set("remove-region", "TempRegion")`
`restart`	Restart all sims in this instance	`set("restart")`
`set region flags`	Set database flags for region	`set("set region flags", "MyRegion DefaultRegion")`
`show neighbours`	Show the local regions' neighbours	`get("show neighbours")`
`show ratings`	Show rating data	`get("show ratings")`
`show region`	Show region parameters	`get("show region")`
`show regions`	Show all regions data (names, coords, ports, estates)	`get("show regions")`

Region Flags: DefaultRegion, FallbackRegion, RegionOnline, NoDirectLogin, Persistent, LockedOut, NoMove, Reservation, Authenticate, Hyperlink, DefaultHGRegion

Scene Commands

Command	Description	Example
`debug scene`	Turn on scene debugging	`set("debug scene", "on")`
`rotate scene`	Rotate scene around 128,128 axis (0-360 degrees)	`set("rotate scene", "90")`
`scale scene`	Scale all scene objects by factor (1.0 = original)	`set("scale scene", "1.2")`
`translate scene`	Move entire scene to new coordinate	`set("translate scene", "10,0,0")`

Script Commands

Command	Description	Example
`scripts resume`	Resume all suspended scripts (or specific script)	`set("scripts resume")`
`scripts show`	Show script information	`get("scripts show")`
`scripts start`	Start all stopped scripts (or specific script)	`set("scripts start")`
`scripts stop`	Stop all running scripts (or specific script)	`set("scripts stop")`
`scripts suspend`	Suspend all running scripts (or specific script)	`set("scripts suspend")`

Stats Commands

Command	Description	Example
`show stats`	Show useful statistical information for this server	`get("show stats")`
`stats record`	Record stats periodically to a separate log file	`set("stats record")`
`stats save`	Save a snapshot of current stats to a file	`set("stats save", "stats.txt")`
`stats show`	Synonym for show stats	`get("stats show")`

Terrain Commands

Command	Description	Example
`terrain bake`	Save current terrain into region's baked map	`set("terrain bake")`
`terrain effect`	Run a specified plugin effect (or list)	`set("terrain effect", "list")`
`terrain elevate`	Raise current heightmap by specified amount	`set("terrain elevate", "5.0")`
`terrain fill`	Fill current heightmap with specified value	`set("terrain fill", "25")`
`terrain flip`	Flip current terrain about X or Y axis	`set("terrain flip", "x")`
`terrain load`	Load terrain from file	`set("terrain load", "terrain.r32")`
`terrain load-tile`	Load terrain from section of larger file	`set("terrain load-tile", "terrain.png 2 2 0 0")`
`terrain lower`	Lower current heightmap by specified amount	`set("terrain lower", "2.5")`
`terrain max`	Set maximum terrain height	`set("terrain max", "100")`
`terrain min`	Set minimum terrain height	`set("terrain min", "0")`
`terrain modify`	Area-of-effect terraforming with optional taper	`set("terrain modify", "raise 10 -ell=128,128,64")`
`terrain multiply`	Multiply heightmap by specified value	`set("terrain multiply", "0.8")`
`terrain newbrushes`	Enable experimental terrain brushes	`set("terrain newbrushes", "true")`
`terrain rescale`	Rescale terrain to fit between min/max heights	`set("terrain rescale", "0 100")`
`terrain revert`	Load baked map terrain into heightmap	`set("terrain revert")`
`terrain save`	Save current heightmap to file	`set("terrain save", "terrain.png")`
`terrain save-tile`	Save heightmap to section of larger file	`set("terrain save-tile", "terrain.png 2 2 0 0")`
`terrain show`	Show terrain height at given coordinate	`get("terrain show", "128 128")`
`terrain stats`	Show heightmap info for debugging	`get("terrain stats")`

Supported formats: .r32, .f32, .ter, .raw, .jpg, .jpeg, .bmp, .png, .gif, .tif, .tiff

Tree Commands

Command	Description	Example
`tree active`	Change activity state for trees module	`set("tree active", "true")`
`tree freeze`	Freeze/unfreeze activity for a defined copse	`set("tree freeze", "CopseName")`
`tree load`	Load a copse definition from XML file	`set("tree load", "copse.xml")`
`tree plant`	Start planting on a copse	`set("tree plant", "CopseName")`
`tree rate`	Reset tree update rate (milliseconds)	`set("tree rate", "1000")`
`tree reload`	Reload copse definitions from in-scene trees	`set("tree reload")`
`tree remove`	Remove copse definition and all its trees	`set("tree remove", "CopseName")`
`tree statistics`	Log statistics about the trees	`get("tree statistics")`

User Commands

Command	Description	Example
`alert`	Send in-world alert to everyone	`set("alert", "Server restarting in 5 minutes")`
`alert-user`	Send in-world alert to specific user	`set("alert-user", "First Last Your message")`
`bypass permissions`	Bypass in-world permission checks	`set("bypass permissions", "true")`
`debug permissions`	Turn on permissions debugging	`set("debug permissions", "on")`
`force permissions`	Force permissions on or off	`set("force permissions", "on")`
`kick user`	Kick a user off the simulator	`set("kick user", "First Last Please relog")`
`login disable`	Disable user entry to this simulator	`set("login disable")`
`login enable`	Enable user entry to this simulator	`set("login enable")`
`login status`	Show whether logins are enabled or disabled	`get("login status")`
`show users`	Show info about connected users (full for child agents)	`get("show users")`, `get("show users", "full")`
`teleport user`	Teleport a user to a specific destination	`set("teleport user", "First Last RegionName")`

Windlight/LightShare Commands

Command	Description	Example
`windlight disable`	Disable the windlight plugin	`set("windlight disable")`
`windlight enable`	Enable the windlight plugin	`set("windlight enable")`
`windlight load`	Load windlight profile from database and broadcast	`set("windlight load")`

YEngine Commands

Command	Description	Example
`yeng cvv`	Show compiler version value	`get("yeng cvv")`
`yeng help`	Show YEngine help	`get("yeng help")`
`yeng ls`	List scripts (options: -full, -max, -topcpu, -queues)	`get("yeng ls")`, `get("yeng ls", "-full -max=50")`
`yeng mvv`	Show/set migration version value	`get("yeng mvv")`, `set("yeng mvv", "1")`
`yeng pev`	Post event to scripts	`set("yeng pev", "-all touch_start 1")`
`yeng reset`	Reset scripts (-all or by name)	`set("yeng reset", "-all")`
`yeng resume`	Resume script processing	`set("yeng resume")`
`yeng suspend`	Suspend script processing	`set("yeng suspend")`
`yeng tracecalls`	Enable/disable call tracing	`set("yeng tracecalls", "yes")`
`yeng verbose`	Enable/disable verbose output	`set("yeng verbose", "yes")`

ROBUST Service Commands

These commands are available on the ROBUST console (or standalone console).

Asset Service

Command	Description	Example
`delete asset`	Delete an asset from the database	`set("delete asset", "<asset-uuid>")`
`dump asset`	Dump an asset to the filesystem	`set("dump asset", "<asset-uuid>")`
`show asset` / `show digest`	Show summary information about an asset	`get("show asset", "<asset-uuid>")`

Grid Service

Command	Description	Example
`deregister region id`	Deregister a region manually	`set("deregister region id", "<region-uuid>")`
`set region flags`	Set database flags for region	`set("set region flags", "MyRegion DefaultRegion")`
`show region at`	Show details on region at given coordinate	`get("show region at", "1000 1000")`
`show region name`	Show details on a region by name	`get("show region name", "MyRegion")`
`show regions`	Show details on all regions	`get("show regions")`

User Service

Command	Description	Example
`create user`	Create a new user account	`set("create user", "First Last password email")`
`reset user password`	Set a new password for a user	`set("reset user password", "First Last newpass")`
`show account`	Show account details for given user	`get("show account", "First Last")`

Login Service

Command	Description	Example
`login level`	Set minimum user level allowed to login	`set("login level", "200")`
`login reset`	Reset login level to default value	`set("login reset")`
`login text`	Set text to display during login	`set("login text", "Welcome to the grid!")`
`set user level`	Set user level (god status, login permission)	`set("set user level", "First Last 200")`

HyperGrid Commands

Command	Description	Example
`link-mapping`	Set local grid coordinate for remote hypergrid mapping	`set("link-mapping", "1000 1000")`
`link-region`	Link a HyperGrid region at specified coordinates	`set("link-region", "8998 8998 grid.example.com 9006 \"Name\"")`
`show hyperlinks`	List all hypergrid linked regions	`get("show hyperlinks")`
`unlink-region`	Unlink a hypergrid region by local name	`set("unlink-region", "\"Remote Region\"")`

Generic / Raw Commands

Command	Description	Example
Any command	Execute any raw console command	`run("any raw console command")`

License

MIT License

opensim-mcp