moo-mcp

moo-mcp

MCP server for LambdaMOO administration. Connects to a MOO's admin/wizard port over TCP, keeps the connection warm, and exposes structured tools for the operations you actually do when hacking on a MOO: eval expressions, list/program verbs (with auto read-back verification), add/remove properties, walk the inheritance chain.

Use with Claude Code or any other MCP-compatible client.

Why

The usual MOO admin loop is "telnet in, run a command, read the response, repeat" - slow and lossy when scripted, and @program famously prints "0 errors" even when the verb body didn't actually get stored as you expected. moo-mcp wraps that loop in a persistent process with proper request/response semantics and adds an automatic read-back verify on every verb program so silent corruption is impossible.

Status

Alpha. Tested against LambdaMOO 1.8.3-Mongoose. Should work against any MOO whose admin port speaks the standard ;eval, @list, @program ... . protocol.

Install

pip install moo-mcp

Or from source:

git clone https://github.com/<org>/moo-mcp
cd moo-mcp
pip install -e .

Configure

moo-mcp is config-free out of the box - you must provide connection details via environment variables. There are no defaults pointing at any particular MOO.

| Env var | Required | Description | |---|---|---| | MOO_HOST | yes | Hostname or IP of the MOO admin port | | MOO_PORT | yes | TCP port (e.g. 7777, 3500) | | MOO_USER | yes | Wizard character name | | MOO_PASS | yes | Wizard password | | MOO_TIMEOUT | no | Seconds to wait for a response (default 15) | | MOO_RECONNECT | no | true/false, auto-reconnect on drop (default true) | | MOO_TLS | no | true/false, wrap the connection in TLS (default false). Use this when the MOO is fronted by stunnel or otherwise serves the admin port over TLS. | | MOO_TLS_INSECURE | no | true/false, skip TLS certificate validation (default false). Only enable for self-signed certs on a MOO you control. |

Use with Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "moo": {
      "command": "python",
      "args": ["-m", "moo_mcp"],
      "env": {
        "MOO_HOST": "your.moo.example.com",
        "MOO_PORT": "7777",
        "MOO_USER": "Wizard",
        "MOO_PASS": "supersecret"
      }
    }
  }
}

Or run directly:

MOO_HOST=... MOO_PORT=... MOO_USER=... MOO_PASS=... python -m moo_mcp

Tools

| Tool | Description | |---|---| | eval | Evaluate a MOO expression; returns parsed value or structured error | | list_verb | Read a verb body; returns header + numbered lines | | program_verb | Replace a verb body; auto-verifies by re-listing and diffing | | add_verb / remove_verb / chmod_verb | Verb lifecycle | | add_property / remove_property / set_property | Property lifecycle | | has_verb / has_property | Check existence (returns the defining-object list) | | verbs / properties | List local verbs/properties on an object | | parent / chparent | Read or change an object's parent |

All tools return JSON results. MOO errors (E_PROPNF, traceback) become structured {error: {message, traceback}} objects rather than raw text.

Security

moo-mcp is a wizard-privileged admin tool, equivalent in capability to a logged-in human wizard at the MOO admin port. Anyone who can call its tools can do anything a wizard can. Run it in a trust boundary that matches.

Specific notes:

• The stock MOO admin protocol is plaintext. Username and password are sent over the TCP socket unencrypted, the same way a telnet session would. If your MOO is not on the same host as the MCP and not already TLS-wrapped, either: (a) set MOO_TLS=true if your MOO is fronted by stunnel or otherwise serves the admin port over TLS, or (b) run the MCP through an SSH tunnel to the MOO host.
• eval_moo gives full wizard eval access. This is by design. Do not expose this MCP to untrusted clients.
• program_verb rejects bare-dot lines in the body (they would terminate the @program block and let the rest land in the command parser). If you need a literal . line in MOO code, indent it.
• add_verb validates the verb arg-spec (dobj / iobj must be this/any/none, prep is allowlist-character-checked) to prevent breaking out of the MOO double-quoted literal during eval splice.
• set_property / add_property value serializer escapes backslashes, double quotes, carriage returns, line feeds, and NUL bytes in string values so a malicious property value cannot break out of the MOO source.
• Connection config rejects CR/LF/NUL in MOO_USER / MOO_PASS to prevent command injection at login time.
• search_verbs accepts user-provided regex. A pathological pattern can cause catastrophic backtracking. Python's re has no built-in timeout. Trust the caller, or pre-validate patterns if you're exposing this to untrusted input.
• No persistent state: no on-disk caching, no logging of passwords, no telemetry. Connection credentials live only in env vars; in-flight commands live in process memory.

License

MIT