Provides tools for storing and retrieving data on the Walrus decentralized storage network, with blockchain coordination through Sui for storage metadata, epoch management, and proof of availability verification.
🦭 Walrus MCP Server
MCP Server for Walrus Decentralized Storage Protocol
Built with ❤️ by
🌐 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-mcpInstall dependencies
npm installBuild the server
npm run build
MCP Setup
Add to your Claude Desktop configuration:
🛠️ 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 |
| Start development server |
| Build for production |
| Start production server |
| Run ESLint |
| Run TypeScript type checking |
| 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).
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
:
Tool Usage Examples
Storing a Blob
Retrieving a Blob
Getting Blob Information
Resource Usage Examples
Check Network Status
View Configuration
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:
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:
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
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.
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
- -securityAlicense-qualityA 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 -9MIT License
- -securityAlicense-qualityProvides 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 -58MIT License
- -securityAlicense-qualityEnables AI applications to interact with decentralized storage through a standardized Model Context Protocol interface, allowing file uploads, retrievals, and identity management.Last updated -12Apache 2.0
- -securityFlicense-qualityEnables AI assistants like Claude to interact with Databricks workspaces through secure OAuth authentication. Supports custom prompts, tools for cluster management, SQL execution, and job operations via the Databricks SDK.Last updated -16