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 file for details.

Attribution

This project uses the MVMF libraries developed by Metaversal Corporation.

See the 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.