opensim-metaverse2mcp：基于 LibreMetaverse 的 OpenSim 机器人 MCP 服务器

opensim-metaverse2mcp is a LibreMetaverse-based OpenSim bot that exposes bot actions as MCP tools over Streamable HTTP.

The server logs in the bot on startup (no separate login tool), then serves MCP at a configurable HTTP endpoint.

Important

LibreMetaverse 3.1.8 introduces stricter certificate handling and safer Collada texture resolution defaults. Existing deployments that relied on self-signed or untrusted TLS certs can fail to connect after upgrading.

If your grid uses private/self-signed certs, set one of the following before upgrading:

Preferred: OPENSIM_SECURITY_CA_BUNDLE_PATH to a PEM CA bundle.
Pin a specific cert by SHA-256 fingerprint: OPENSIM_SECURITY_TRUST_CERTIFICATE=<fingerprint>.
Last resort (lower security): OPENSIM_SECURITY_VERIFY_SERVER_CERTIFICATES=false.

This is part of the opensim-stack and is intended to be used in conjunction with other parts of the stack. See Docs for full details.

For Issues And Discussions see main project opensim-ai-docker

What it does

Uses LibreMetaverse (3.1.8) to connect to OpenSim/SL-compatible grids.
Routes avatar IM conversations to Opencode server sessions with NOpenCode.
Uses MCP tools for avatar actions that the AI can invoke via Opencode.
Exposes MCP tools with the official C# MCP libraries:
- ModelContextProtocol
- ModelContextProtocol.AspNetCore
Supports config via environment variables and CLI args (CLI overrides env).
Gives the Bot a voice via Piper and WebRTC (Janus) - Other stack parts required

Volumes

Name	Description
/config	Various configuration files
/cache	Client cache

Configuration

The Bot can only be instructed by a Handler. You must define who the bot handler is (i.e. you), in /config/handlers.json. E.g if your name is Alice McSim

[ {
  "botFirst" : "*",
  "botLast" : "*",
  "handlerFirst" : "Alice",
  "handlerLast" : "McSim"
} ]

Note, this only applies to instructions by chat. MCP tool calls are not restricted

Run

Assuming you are in the same directory as where a config directory also exists with the above Handler configuration.

docker run --rm \
  -e OPENSIM_BOT_FIRST=Governor \
  -e OPENSIM_BOT_LAST=Bot \
  -e OPENSIM_BOT_PASSWORD=botpassword \
  -e OPENSIM_LOGIN_URI=http://host.docker.internal:9000 \
  -e MCP_TRANSPORT=http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8999 \
  -e MCP_HTTP_ENDPOINT=/mcp \
  -p 8999:8999 \
  -v config:/config \
  -v cache:/cache \
  bithatch/opensim-metaverse2mcp:latest

Environment Variables

Bot login (required)

OPENSIM_BOT_FIRST
OPENSIM_BOT_LAST
OPENSIM_BOT_PASSWORD

Bot login (optional)

OPENSIM_BOT_GROUP
OPENSIM_LOGIN_URI (default: http://opensim:9000)
OPENSIM_LOGIN_START (default: last)
OPENSIM_LOGIN_TIMEOUT_SECONDS (default: 30)
OPENSIM_SECURITY_TRUST_CERTIFICATE (optional SHA-256 certificate fingerprint string)
OPENSIM_SECURITY_CA_BUNDLE_PATH (optional PEM CA bundle path)
OPENSIM_SECURITY_VERIFY_SERVER_CERTIFICATES (default: true)
OPENSIM_RESTRICT_TEXTURES_TO_MODEL_DIRECTORY (default: true)
OPENSIM_CACHE (default /app/linden/cache)
OPENSIM_CACHE_ENABLED (default true)
OPENSIM_CACHE_MAXSIZE (default 1073741824 - 1GB)

Spawner API integration

SPAWNER_HOST (default: opensim-ai-spawner)
SPAWNER_PORT (default: 8993)
SPAWNER_TOKEN (optional bearer token for spawner auth)
Bot-management API path is fixed to /api/bot (for example GET /api/bot, POST /api/bot/{first}/{last}).

MCP server

METAVERSE_MCP_TRANSPORT (http or sse; default: http)
METAVERSE_MCP_HOST (default: 0.0.0.0)
METAVERSE_MCP_PORT (default: 8999)
METAVERSE_MCP_HTTP_ENDPOINT (default: /mcp)
METAVERSE_MCP_HTTP_BEARER_TOKEN (optional)
METAVERSE_MCP_HTTP_DISALLOW_DELETE (true/false, default: false)
METAVERSE_MCP_DIAGNOSTICS (true/false, default: false)
INVENTORY_OFFER_POLICY_FILE (optional JSON file path)
INVENTORY_OFFER_POLICY_AUTOSAVE (true/false, default: true)

Opencode chat bridge

OPENCODE_ENABLED (true/false, default: true) — master switch for the built-in opencode brain. Set false for standalone MCP-driven bots that bring their own mind: the /event observer loop and IM/group auto-routing (including fallback replies) are skipped, while bridge-side MCP events (chat.im.received, chat.local.received) keep flowing.
OPENCODE_SCHEME (http or https, default: http)
OPENCODE_HOST (default: opensim-opencode)
OPENCODE_PORT (default: 8998)
OPENCODE_SERVER_USERNAME (optional Basic auth username)
OPENCODE_SERVER_PASSWORD (optional Basic auth password)
OPENCODE_REQUEST_TIMEOUT_SECONDS (default: 1800)

Voice routing (Piper + grid voice)

VOICE_ROUTING_ENABLED (true/false, default: false)
VOICE_BACKEND (webrtc, default: webrtc)
PIPER_SCHEME (http or https, default: http)
PIPER_HOST (default: opensim-ai-piper-1)
PIPER_PORT (default: 8995)
PIPER_TTS_PATH (default: /tts)
PIPER_VOICES_PATH (default: /voices)
PIPER_TIMEOUT_SECONDS (default: 60)
PIPER_DEFAULT_VOICE (default: en_US-lessac-medium)

Layered prompt handling

PROMPT_HANDLING_ENABLED (true/false, default: true)
PROMPT_BUILTIN_ENABLED (true/false, default: true)
PROMPT_PROJECT_AGENTS_ENABLED (true/false, default: true)
PROMPT_PROJECT_AGENTS_FILE (default: AGENTS.md)
PROMPT_NOTECARD_ENABLED (true/false, default: true)
PROMPT_NOTECARD_REQUIRE_HANDLER (true/false, default: true)
PROMPT_MAX_CHARS (default: 16000, minimum effective clamp: 512)

This repository includes a starter project prompt file at AGENTS.md.

Notes:

MCP_TRANSPORT=sse enables legacy SSE compatibility in the MCP HTTP transport.
This server always runs MCP over HTTP (streamable transport), not stdio.

Building and publishing

See BUILDING.md for local build/run steps, manual multiarch publish commands, and automated GitHub Actions publish details.

TOOLS.md - More information about the MCP tools exposed themselves
DEVELOPMENT.md - If you want to make changes to the MCP server, if you want to run without Docker etc.
BUILDING.md - Other building instructions.