XNS Relayer MCP
About
Install and manage a self-hosted XNS Relayer (S3-compatible distributed object storage) conversationally — 15 tools, npx-ready, stdio transport.
Details
- Author
- xns-cloud
- Categories
- File Management, Other
Jump to
Setup
Install XNS Relayer MCP in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/xns-cloud/relayer-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Pricing:$6.00 per TB-month— one rate, protection included,$0 egress uncapped,30-day minimum retentionwith no separate early-delete fee.
- Node.js 20+— seeInstalling Node.js 20if your distro ships an older version.
- Docker Engine— on the same machine, or on a remote host via a Docker context (seeRemote Docker hosts).
Ubuntu's default apt repository only ships Node 18, which is too old. Two ways to get Node 20:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash \. "$HOME/.nvm/nvm.sh" && nvm install 20
NodeSource(system-wide): followhttps://github.com/nodesource/distributions#installation-instructions.
If you start the MCP on an older Node, it exits immediately with this same guidance instead of a dependency stack trace.
The Relayer runs as a Docker container and persists its data in a Docker volume. If the MCP is running inside an ephemeral environment (a sandbox container, a CI runner, or a throwaway VM), any installation performed there will be lost when that environment exits.check_prerequisitesdetects this automatically and reports it as a warning with a concrete next step — it never blocks the flow.
If your environment is ephemeral, install on a persistent Docker host instead. The easiest path from an ephemeral sandbox is an SSH Docker context:
docker context create relayer --docker "host=ssh://user@persistent-host" docker context use relayer
The MCP then drives the install on the persistent host through the SSH context. Alternatively, hand the install step to a human operator on the target machine and continue onboarding fromcheck_relayer_healthonwards.
claude mcp add relayer -- npx @xns-cloud/relayer-mcp@latest
Claude Desktop / any MCP client— add to yourclaude_desktop_config.json(or equivalent):
{ "mcpServers": { "relayer": { "command": "npx", "args": ["@xns-cloud/relayer-mcp@latest"] } } }
{ "mcpServers": { "relayer": { "command": "npx", "args": ["@xns-cloud/relayer-mcp@latest"] } } }
No separate install step required — npx fetches the package on demand.
- Agent checks prerequisites (Tool 1).
- Agent gets the browser sign-up URL; user creates an account in the browser (Tool 2).
- User clicks email verification link; agent polls (Tool 3).
- Agent installs and starts Relayer containers (Tool 4) — it writes the released compose +.envitself; the user is never asked for a compose URL.
- Agent polls health until UI + S3 are up (Tool 5).
- Agent initiates claim; user opens claim URL in browser (Tools 6 + 7).
- Agent signs in via OIDC to configure host preferences (Tools 8 + 9).
- Agent verifies S3 storage is working (Tool 10).
- Optionally, agent provisions CLI credentials (Tool 11).
The operator's only required actions are: clicking one email link, completing one browser sign-in, and confirming one claim.
After onboarding, tools 12-15 cover routine adjustments:describe_settings→update_settings→restart_servicefor tuning (workers, concurrency, backup schedule, cost center), andmanage_backupsfor the backup lifecycle. All four use the same OIDC session as tools 8-9. Destructive operations (restore, restart, changing the cost center) are agent-confirmed with the operator before execution — the tool descriptions and responses carry the warnings.
install_relayerperformsfresh installs only— it does not upgrade an existing deployment in place. Docker container names are unique per daemon, so any existingxns-relayercontainer (runningor stopped, any channel — including an alpha-channel install fromreleases.scpri.me) blocks the install. Bothcheck_prerequisitesandinstall_relayerdetect this and tell you before anything breaks.
docker stop xns-relayer && docker rm xns-relayer # does NOT delete the data directory
then runinstall_relayeragain. To keep the existing deployment, skipinstall_relayerand continue onboarding against it (check_relayer_healthonwards).
Claude Code doesn't have to run on the Docker machine. If you run it on a management node or jump host, point the Docker CLI at the remote server with an SSH context:
docker context create relayer --docker "host=ssh://user@docker-box" docker context use relayer
(Requires thedockerCLI on the management node — thestatic binaryis enough — and SSH key access to the Docker host.)
The MCP detects this automatically (it honorsDOCKER_HOSTand the active Docker context):
- install_relayerrunsdocker composeagainst the remote daemon.
- check_relayer_healthandverify_storageprobe theremote host'sports 8888/9000 instead of localhost — make sure those are reachable from the management node.
- check_prerequisitesskips the local port-availability probes (the containers bind ports on the remote host) and reports them as skipped with instructions.
check_relayer_healthaccepts ahostoverride, andverify_storageanendpointoverride, for setups the auto-detection can't see (port forwards, NAT).
Tools 8-9 and 12-15 require an OIDC token to access the Relayer API and HostIO proxy. The MCP acquires one automatically using Authorization Code + PKCE (S256) flow against thescprimeKeycloak realm with therelayer-nativepublic client. The user completes a browser sign-in; the MCP captures the code on a local127.0.0.1loopback listener and exchanges it for a token.
Prerequisite:Therelayer-nativepublic client must be registered on the Keycloakscprimerealm (PKCE S256, redirecthttp://127.0.0.1:).
This package uses therelayer-nativeKeycloak client ID for OIDC authentication. The same client ID is intended for reuse by a future standalone Relayer CLI (@xns-cloud/relayer-cli), with the OIDC module (src/lib/oidcAuth.js) extracted to a shared@xns-cloud/relayer-authpackage.
Canonical policy:https://xns.tech/privacy-policy/. Product-specific detail for this server is inPRIVACY.md.
- No telemetry.No analytics, crash reporting, or usage counters. It does not phone home.
- Tokens live in memory only.OIDC access tokens are never written to disk; they are discarded when the process exits.
- The agent never sees your password.Sign-in happens in your own browser againstauth.xns.tech.
- Private network only.No tool can be pointed at a public Relayer: the ones taking a host argument run it through an allowlist (localhost, loopback, RFC 1918,.local), and the rest expose no URL parameter and are fixed tolocalhost. The three XNS services it contacts areauth.xns.tech,console.xns.tech, andreleases.scpri.me.
- Your stored objects never pass through it.The Relayer you host handles your data directly.
The same server ships as anMCP Bundlefor one-click install in Claude Desktop. Build it from a clean checkout:
That reinstalls production-only dependencies, validates the manifest, and writes the.mcpb. The MCPB CLI version is pinned in the script — do not invoke it unversioned, or the bundle you ship is not the bundle that was validated. Runnpm ciafterwards to get the dev dependencies back for testing.
To validate the manifest alone without repacking:
manifest.jsonat the repo root is the bundle manifest.mcpbManifest.test.jspins itsversionand tool list topackage.json,server.json, and the running server, so drift fails the suite rather than shipping.
Apache-2.0 © SCP Corp. SeeLICENSEandNOTICE.
Interact with the Intelligent Content Management platform through Box AI.
An MCP server for interacting with AIStor and MinIO object stores.
Access various storage services like S3, GCS, and Azure Blob through the Apache OpenDAL™ project, configured via environment variables.
Manage AWS S3 buckets and objects, including policies, tagging, and configurations.
Manage AWS S3 operations, providing secure access to S3 buckets through pre-signed URLs.
Upload images and videos to Cloudinary from compatible MCP clients.
DeFi agent definitions JSON API - Production-ready agents for Web3, crypto trading, portfolio management, and blockchain automation
GCP Bucket Connector (data-connectors-ai)
Read-only MCP server for GCP Cloud Storage: list objects in a bucket.
Access and manage your Google Photos library with AI assistants.
A server for backing up and restoring data for AI agents and code editing tools.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
