Walrus MCP

The Walrus MCP Server is an MCP server designed for the Walrus decentralized storage protocol, providing functions for storing, retrieving, and managing data blocks, and integrating with the Sui blockchain to manage storage metadata.

Cloud storage Developer tools #Decentralized storage #Blockchain integration #Data management #MCP tools .TypeScript

rating : 2 points

downloads : 4.8K

update time : 2025-08-19

Open Site

What is the Walrus MCP Server?

The Walrus MCP Server is a bridge service that connects AI assistants (such as Claude) with the Walrus decentralized storage network. Through the Model Context Protocol (MCP), it allows AI assistants to easily store, retrieve, and manage data in the decentralized network.

How to use the Walrus MCP Server?

Before use, you need to install the Node.js environment and configure the MCP client. The main functions, including storing data, retrieving data, and getting data information, can all be completed through simple tool calls.

Use cases

It is suitable for scenarios that require long - term storage of AI - generated content, data sharing, or building decentralized applications. It is particularly suitable for applications that need data persistence but do not want to rely on centralized storage services.

Main features

Decentralized storage operations

Supports storing data in the Walrus decentralized network and reliably retrieving the stored data. All data is identified by a unique ID, and the storage status and validity period can be queried.

Blockchain integration

Deeply integrated with the Sui blockchain to manage storage metadata and lifecycle. Verifies data availability through the blockchain to ensure the reliability and transparency of storage.

Developer tools

Provides easy - to - use MCP tools that support direct upload of Base64 - encoded data and file paths. Includes comprehensive error handling and clear prompt information.

Advantages

Decentralized storage, data is not controlled by a single entity

Blockchain verification ensures data authenticity and availability

Simple and easy - to - use API interfaces, seamless integration with AI assistants

Automated data lifecycle management

Limitations

All stored data is publicly accessible by default, not suitable for sensitive information

Storage costs are related to data size and storage duration

Depends on the blockchain network status, and transactions may need to wait for confirmation

How to use

Installation preparation

Ensure that Node.js (version ≥18) and npm are installed on the system. Clone the repository and install dependencies.

Build the server

Use npm to build the project and generate an executable file.

Configure the MCP client

Add server configuration to MCP clients such as Claude Desktop and specify environment variables.

Start using

Call tools to store or retrieve data, or get network status information through resource URLs.

Usage examples

Store AI - generated content

Permanently store AI - generated reports or images in the decentralized network

Share public data

Create a publicly accessible data link for others to view

Check data status

Verify whether important data is still stored in the network

Frequently Asked Questions

Is the stored data private?

Will the data be stored permanently?

Is there a fee for storing data?

How to get SUI tokens to pay for storage fees?

Related resources

Walrus official documentation

Complete technical documentation of the Walrus protocol

MCP documentation

Detailed description of the Model Context Protocol

GitHub repository

Project source code and issue tracking

Motion Labs community

Developer communication and support community

🚀 🦭 Walrus MCP Server

The Walrus MCP Server serves as a crucial bridge for AI assistants to interact with the Walrus decentralized storage network. It offers a wide range of features, including decentralized storage operations, blockchain integration, and a great developer experience.

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm >= 8.0.0
Claude Desktop or a compatible MCP client

Installation

Clone the repository

git clone https://github.com/MotionEcosystem/walrus-mcp.git
cd walrus-mcp

Install dependencies
```
npm install
```
Build the server
```
npm run build
```

MCP Setup

Add the following to your Claude Desktop configuration:

{
  "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"
      }
    }
  }
}

✨ Features

🗄️ Decentralized Storage Operations

Store blobs in the Walrus decentralized storage network.
Retrieve blobs by blob ID with high availability.
Get blob information including size and certification status.
Check blob availability and network health.

🔗 Blockchain Integration

Sui blockchain coordination for storage metadata.
Storage epoch management for blob lifecycle.
Proof of availability through blockchain verification.
Storage resource management.

🛠️ Developer Experience

Simple MCP tools for AI assistants and automation.
Base64 encoding for binary data handling.
File path support for direct file uploads.
Comprehensive error handling with clear messages.

💻 Usage Examples

Basic Usage

// Store text data
await tool_call("store_blob", {
  data: "SGVsbG8sIFdhbHJ1cyE=", // Base64 encoded "Hello, Walrus!"
  epochs: 10
})

// Store a file
await tool_call("store_blob", {
  data: "/path/to/file.jpg",
  epochs: 5
})

// Get blob content as Base64
const blob = await tool_call("get_blob", {
  blobId: "0xabc123..."
})

// Get blob metadata
const info = await tool_call("get_blob_info", {
  blobId: "0xabc123..."
})

console.log(info.size, info.certified, info.endEpoch)

// Get Walrus network health
const status = await resource_read("walrus://status")
console.log(status.epoch, status.networkSize)

// Get current client configuration
const config = await resource_read("walrus://config")
console.log(config.aggregatorUrl, config.publisherUrl)

📚 Documentation

Environment Configuration

Create a .env file based on .env.example:

# 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

Error Handling

The server provides comprehensive error handling for common scenarios:

Blob not found: Clear error message with blob ID.
Network issues: Timeout and connectivity error details.
Invalid data: Validation errors for malformed inputs.
Storage limits: Epoch and capacity constraint messages.

Data Format Support

Supported Input Formats

Base64 encoded strings: For binary data transmission.
File paths: Direct file reading (relative or absolute).
Text content: Automatically encoded for storage.

Output Format

All retrieved blobs are returned as Base64 encoded strings for consistent handling across different data types.

Security Considerations

⚠️ Important Note

All blobs stored in Walrus are public and discoverable.

Do not store sensitive or confidential information without encryption.

Consider client-side encryption for private data.

Validate all inputs before processing.

Network Information

DevNet Configuration

Aggregator: https://aggregator-devnet.walrus.space
Publisher: https://publisher-devnet.walrus.space
System Object: 0x37c0e4d7b36a2f64d51bba262a1791f844cfd88f19c35b5ca709e1a6991e90dc

TestNet Configuration

For TestNet usage, update environment variables:

WALRUS_AGGREGATOR_URL=https://aggregator-testnet.walrus.space
WALRUS_PUBLISHER_URL=https://publisher-testnet.walrus.space

Storage Economics

Epochs and Pricing

Epoch Duration: Fixed time periods for storage commitment.
Minimum Storage: 5 epochs (configurable).
Cost Calculation: Based on blob size and storage duration.
Payment: Handled through Sui blockchain transactions.

Troubleshooting

Common Issues

Connection Errors
- Verify network connectivity.
- Check aggregator/publisher URLs.
- Ensure DevNet/TestNet endpoints are accessible.
Storage Failures
- Check blob size limits.
- Verify sufficient SUI tokens for storage fees.
- Ensure proper epoch configuration.
Retrieval Issues
- Confirm blob ID format and validity.
- Check if blob has expired (past end epoch).
- Verify aggregator availability.

Debug Mode

Enable detailed logging:

DEBUG=walrus-mcp:* npm run dev

Contributing

We welcome contributions! Please:

Fork the repository.
Create a feature branch.
Add tests for new functionality.
Update documentation.
Submit a pull request.

Roadmap

[ ] Enhanced blob management: Batch operations and metadata indexing.
[ ] Encryption support: Client-side encryption for private data.
[ ] WebSocket support: Real-time blob status updates.
[ ] CLI tool: Standalone command-line interface.
[ ] Performance metrics: Storage and retrieval analytics.
[ ] MainNet support: Production network integration.

🔧 Technical Details

Available Tools

Tool Name	Description	Parameters
`store_blob`	Store data in Walrus decentralized storage.	`data` (Base64 encoded data or file path), `epochs` (optional, default: 5)
`get_blob`	Retrieve a blob from Walrus storage.	`blobId`
`get_blob_info`	Get information about a blob.	`blobId`
`list_blobs`	List stored blobs (requires local indexing).	`limit` (optional)
`delete_blob`	Attempt to delete a blob (note: Walrus blobs expire automatically).	`blobId`

Resources

Resource Name	Description
`walrus://status`	Current status and health of the Walrus network.
`walrus://config`	Current Walrus client configuration.

Available Scripts

Script	Description
`npm run dev`	Start development server.
`npm run build`	Build for production.
`npm run start`	Start production server.
`npm run lint`	Run ESLint.
`npm run type-check`	Run TypeScript type checking.
`npm run format`	Format code with Prettier.

Tech Stack

Property	Details
Runtime	Node.js
Language	TypeScript
MCP SDK	@modelcontextprotocol/sdk
HTTP Client	Axios
Validation	Zod

Architecture

The Walrus MCP Server provides a bridge between AI assistants and the Walrus decentralized storage network through the Model Context Protocol (MCP).

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   AI Assistant  │    │  Walrus MCP     │    │ Walrus Network  │
│  (Claude, etc.) │◄──►│     Server      │◄──►│   (DevNet)      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │  Sui Blockchain │
                       │   (Metadata)    │
                       └─────────────────┘

Components

MCP Server: Handles tool calls and resource requests from AI assistants.
Walrus Client: Manages HTTP communication with Walrus aggregator and publisher.
Aggregator: Provides blob retrieval functionality.
Publisher: Handles blob storage operations.
Sui Integration: Manages storage metadata and epochs.