🦭 Walrus MCP Server

<div align="center">

MCP Server for Walrus Decentralized Storage Protocol

Built with ❤️ by Motion Labs

🌐 Walrus Docs • 📚 MCP Documentation

</div>

✨ 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

1. Clone the repository

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

2. Install dependencies

   npm install
   

3. 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

1. Connection Errors

   • Verify network connectivity
   • Check aggregator/publisher URLs
   • Ensure DevNet/TestNet endpoints are accessible

2. Storage Failures

   • Check blob size limits
   • Verify sufficient SUI tokens for storage fees
   • Ensure proper epoch configuration

3. 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:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Update documentation
5. 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

---

<div align="center"> _{Built with 🦭 for the decentralized future} </div>