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

1. OpenSimulator must be running with the REST console enabled. Start OpenSimulator with:

   ./OpenSim -console=rest
   

2. 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