ManifolderMCP

ManifolderMCP

ManifolderMCP is a Model Context Protocol (MCP) server that allows Claude Code and other MCP clients to browse and edit Open Metaverse Spatial Fabric scenes.

It provides a thin MCP tool layer on top of the MVMF protocol libraries via the ManifolderClient JavaScript library.

ManifolderMCP is an open source project created and maintained by Patched Reality, Inc..

Related Projects

• ManifolderClient — JavaScript client library used by this MCP server
• Manifolder — Web-based explorer for visualizing Open Metaverse fabrics

Setup

Prerequisites

• Node.js >= 18
• Access to a Fabric server

Install

npm install
npm run build

Configure

Create ~/.config/manifolder-mcp/config.json:

{
  "default": {
    "fabricUrl": "https://example.com/fabric/fabric.msf",
    "adminKey": "your-admin-token"
  }
}

Resource upload/download uses one of two transports, selected automatically per profile. Either way, resourceUrlPrefix is the URL prefix used to reference uploads in scenes (e.g., /objects/).

WebDAV (used when filesUrl is set) — file operations go over HTTPS WebDAV against the configured endpoint, authenticated with the profile's adminKey as a bearer token:

| Field | Description | |-------|-------------| | filesUrl | WebDAV endpoint for file operations (e.g., https://files-name.example.com/) | | resourceUrlPrefix | URL prefix for referencing uploads in scenes (e.g., /objects/) |

SCP/SSH (used when filesUrl is absent) — file operations go over SFTP:

| Field | Description | |-------|-------------| | scpHost | SSH hostname for resource uploads | | scpUser | SSH username | | scpRemotePath | Server path where files are written (supports ~) | | scpKeyPath | Path to SSH private key (supports ~) | | resourceUrlPrefix | URL prefix for referencing uploads in scenes (e.g., /objects/) |

Hosts listed in unsafeHosts skip TLS certificate verification (self-signed certs, incomplete chains) for both the fabric socket and WebDAV requests.

Multiple profiles can be defined (e.g., "default", "staging") and selected per-call via the profile parameter on any tool.

Add to MCP Client

Build first (npm run build), then register using an absolute path to dist/index.js.

Claude Code:

claude mcp add --scope user manifolder -- node /absolute/path/to/ManifolderMCP/dist/index.js

Codex:

codex mcp add manifolder -- node /absolute/path/to/ManifolderMCP/dist/index.js

Gemini CLI:

gemini mcp add -s user manifolder node /absolute/path/to/ManifolderMCP/dist/index.js

Manual config (Claude Code settings.json, Gemini settings.json, etc.):

{
  "mcpServers": {
    "manifolder": {
      "command": "node",
      "args": ["/absolute/path/to/ManifolderMCP/dist/index.js"]
    }
  }
}

Tools

Every tool that touches a scope accepts one of scopeId, profile, or url to identify the target. Passing profile or url auto-connects if needed.

Connection & Scopes

| Tool | Purpose | |------|---------| | list_profiles | List connection profiles from config | | fabric_status | Get scope connection state and info | | list_scopes | List active scopes and relationships | | follow_attachment | Open a child scope from an attachment object | | close_scope | Close a scope and optionally its descendants |

Scenes

| Tool | Purpose | |------|---------| | list_scenes | List scenes (paginated) | | open_scene | Load a scene and return root object details | | create_scene | Create a new scene | | delete_scene | Delete a scene and all children |

Objects

| Tool | Purpose | |------|---------| | get_object | Get full object details | | list_objects | List loaded objects under an anchor (shallow, paginated) | | find_objects | Search by name, position radius, or resource URL (paginated) | | find_earth_attachment_parent | Find the smallest terrestrial parent for an Earth attachment and compute attachment geometry | | create_object | Create object (3D model, container, or action resource) | | update_object | Update name, transform, resource, bound, orbit, properties | | delete_object | Delete object and children | | move_object | Reparent object | | bulk_update | Batch create/update/delete/move across scopes |

Resources

| Tool | Purpose | |------|---------| | upload_resource | Upload a file (.glb, .png, .json, etc.) | | download_resource | Download a file from the server | | list_resources | List server files (supports path, recursive, glob filter) | | delete_resource | Remove a file | | move_resource | Move or rename a file | | bulk_upload_resources | Upload multiple files | | bulk_download_resources | Download multiple files | | bulk_delete_resources | Delete multiple files | | bulk_move_resources | Move/rename multiple files |

Action Resources

| Tool | Purpose | |------|---------| | get_action_resource_schema | Get JSON schema for action resource types | | validate_action_resource | Validate an action resource file |

Action types: action://pointlight, action://showtext, action://rotator, action://video.

Usage Example

> List my fabric profiles
> List scenes using profile "default"
> Open scene Playground  
> Create an object named "Tree" under the Nature node
> Move it 5 meters north

Development

npm run dev                      # TypeScript watch mode
npm test                         # Unit tests
npm run test:integration         # Integration tests (requires running server)
npm run test:record-fixtures     # Record test fixtures from live server
npm run sync:manifolder-client   # Sync ManifolderClient from ../Manifolder/

Project Structure

src/
  index.ts              # MCP server entry point
  config.ts             # Connection profile loader
  output.ts             # Pagination helpers
  agent-guide.md        # Tool docs served to MCP clients
  client/               # ManifolderClient (synced from ../Manifolder/)
  tools/                # MCP tool implementations
  storage/              # SCP-based file storage
  vendor/               # MVMF protocol libraries (Node.js shimmed)

The ManifolderClient is shared with the sibling Manifolder project. Edit there, then npm run sync:manifolder-client to pull changes here.

License

Licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.

Attribution

This project uses the MVMF libraries developed by Metaversal Corporation.

See the [NOTICE](NOTICE) file for full attribution details.

Contributing

Contributions are welcome. By submitting a pull request, you agree that your contribution will be licensed under the Apache License, Version 2.0.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: PatchedReality
• Source: PatchedReality/ManifolderMCP
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.