🦭 Walrus MCP Server
✨ 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
Built with 🦭 for the decentralized future