Walrus

You use the Walrus MCP Server to bridge AI assistants with the Walrus decentralized storage network. It exposes a set of MCP endpoints that let you store, retrieve, and inspect blobs, while coordinating with the Sui blockchain for metadata and epoch management. This server is designed for straightforward integration with AI workflows and automation, enabling you to manage Walrus blobs through familiar MCP tooling.

How to use

To operate the Walrus MCP Server, configure your MCP client to connect to the local stdio server and then use the provided tools to store, fetch, and manage blobs. The server exposes a set of endpoints that handle storing data, retrieving blobs by ID, obtaining blob information, listing stored blobs, and deleting blobs (noting that Walrus blobs expire automatically). You can extend functionality through standard MCP tool calls and listen to network health/status via the Walrus endpoints.

How to install

Prerequisites: install and verify Node.js is available on your system.

1. Clone the Walrus MCP repository.

2. Install dependencies.

3. Build the server.

Additional setup and usage notes

To run the MCP server locally, you start the server using Node.js and point to the built index file. You then configure your MCP client to communicate with the Walrus server using the provided environment endpoints.

{
  "mcpServers": {
    "walrus": {
      "command": "node",
      "args": ["path/to/walrus-mcp/dist/index.js"],
      "env": {
        "WALRUS_AGGREGATOR_URL": "https://aggregator-devnet.walrus.space",
        "WALRUS_PUBLISHER_URL": "https://publisher-devnet.walrus.space"
      }
    }
  }
}

Configuration and environment

Create an environment configuration to point the MCP server to Walrus endpoints and optionally set wallet and system object details.

# Required: Walrus network endpoints
WALRUS_AGGREGATOR_URL=https://aggregator-devnet.walrus.space
WALRUS_PUBLISHER_URL=https://publisher-devnet.walrus.space

# Optional: Custom system object ID
WALRUS_SYSTEM_OBJECT=0x37c0e4d7b36a2f64d51bba262a1791f844cfd88f19c35b5ca709e1a6991e90dc

# Optional: Wallet for transaction signing
WALRUS_WALLET_PATH=/path/to/your/wallet.json

Security considerations

Blobs stored in Walrus are public and discoverable. Do not store sensitive data without encryption, and consider client-side encryption for private data. Validate inputs before processing.

Troubleshooting

If you encounter connection errors, verify network connectivity and that the Walrus endpoints are reachable. For storage failures, check blob size limits and ensure sufficient tokens for storage costs. For retrieval issues, confirm the blob ID format and whether the blob has expired.

Enable detailed logging during debugging by starting the server with a verbose log channel.

Tools available through the Walrus MCP Server

The following tool endpoints are available to interact with Walrus storage via MCP. Use them through your MCP client to perform storage operations.

Resource endpoints

Check current Walrus network status and the local client configuration via the built-in resource endpoints.

Development notes

Development scripts let you run the server in development, build for production, start the production server, lint, type-check, and format the codebase.

Available tools

store_blob

Store data in Walrus storage. Accepts base64 data or a file path and an optional epochs count for storage duration.

get_blob

Retrieve a blob by its blob ID. Returns the blob content encoded as Base64.

get_blob_info

Obtain metadata for a blob, including size, certification status, and end epoch.

list_blobs

List stored blobs (requires local indexing) with an optional limit.

delete_blob

Attempt to delete a blob; note that Walrus blobs expire automatically.