Walrus MCP Server

🦭 Walrus MCP Server

MCP Server for Walrus Decentralized Storage Protocol

Built with ❤️ by Motion Labs

🌐 Walrus Docs • 📚 MCP Documentation

✨ Features

🗄️ Decentralized Storage Operations

Store blobs in 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

🚀 Quick Start

Prerequisites

Node.js >= 18.0.0
npm >= 8.0.0
Claude Desktop or 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 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"
      }
    }
  }
}

🛠️ Available Tools

`store_blob`

Store data in Walrus decentralized storage.

data: Base64 encoded data or file path
epochs (optional): Number of epochs to store (default: 5)

`get_blob`

Retrieve a blob from Walrus storage.

blobId: The blob ID to retrieve

`get_blob_info`

Get information about a blob.

blobId: The blob ID to get information about

`list_blobs`

List stored blobs (requires local indexing).

limit (optional): Maximum number of blobs to list

`delete_blob`

Attempt to delete a blob (note: Walrus blobs expire automatically).

blobId: The blob ID to delete

📊 Resources

`walrus://status`

Current status and health of the Walrus network

`walrus://config`

Current Walrus client configuration

🔧 Development

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

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

📚 Detailed 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

Tool Usage Examples

Storing a Blob

// 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
})

Retrieving a Blob

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

Getting Blob Information

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

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

Resource Usage Examples

Check Network Status

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

View Configuration

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

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 Security Notes:

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

📄 License

MIT License - see LICENSE file for details.

🤝 Support

Documentation: Walrus Official Docs
Community: Motion Labs Discord
Issues: GitHub Issues
Email: hello@motionecosystem.com

Install Server

HTTP connection URL

security – no known vulnerabilities

license - not found

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables AI assistants to store and retrieve data using the Walrus decentralized storage network. Supports blob storage operations, retrieval by ID, and blockchain-verified availability through the Sui network.

Related MCP Servers

obsidian-mcp
StevenStavrakis
-
security
A
license
-
quality
Enables AI assistants to interact with Obsidian vaults, providing tools for reading, creating, editing and managing notes and tags.
Last updated -
249
482
TypeScript
MIT License
MCP Blockchain Server
zhangzhongnan928
-
security
A
license
-
quality
A secure system enabling AI assistants to interact with blockchain data and prepare transactions while ensuring users maintain exclusive control over their private keys and transaction signing.
Last updated -
9
TypeScript
MIT License
Obsidian MCP REST Server
PublikPrinciple
-
security
A
license
-
quality
Provides a standardized interface for AI assistants to interact with Obsidian vaults through a local REST API, enabling reading, writing, searching, and managing notes.
Last updated -
52
TypeScript
MIT License
StarRocks MCP Serverofficial
StarRocks
A
security
A
license
A
quality
Acts as a bridge between AI assistants and StarRocks databases, allowing for direct SQL execution and database exploration without requiring complex setup or configuration.
Last updated -
6
102
Python
Apache 2.0

View all related MCP servers