Walrus MCP Server

# 🦭 Walrus MCP Server <div align="center"> **MCP Server for Walrus Decentralized Storage Protocol** _Built with ❤️ by [Motion Labs](https://motionecosystem.com)_ [](https://opensource.org/licenses/MIT) [](https://nodejs.org/) [](https://www.typescriptlang.org/) [🌐 Walrus Docs](https://docs.wal.app/) • [📚 MCP Documentation](https://modelcontextprotocol.io/docs) </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** ```bash git clone https://github.com/MotionEcosystem/walrus-mcp.git cd walrus-mcp ``` 2. **Install dependencies** ```bash npm install ``` 3. **Build the server** ```bash npm run build ``` ### MCP Setup Add to your Claude Desktop configuration: ```json { "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](https://nodejs.org/) - **Language**: [TypeScript](https://www.typescriptlang.org/) - **MCP SDK**: [@modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk) - **HTTP Client**: [Axios](https://axios-http.com/) - **Validation**: [Zod](https://zod.dev/) ## 🏗️ 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`: ```bash # 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 ```typescript // 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 ```typescript // Get blob content as Base64 const blob = await tool_call("get_blob", { blobId: "0xabc123..." }) ``` #### Getting Blob Information ```typescript // 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 ```typescript // Get Walrus network health const status = await resource_read("walrus://status") console.log(status.epoch, status.networkSize) ``` #### View Configuration ```typescript // 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: ```bash 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: ```bash 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](LICENSE) file for details. ## 🤝 Support - **Documentation**: [Walrus Official Docs](https://docs.wal.app/) - **Community**: [Motion Labs Discord](https://discord.gg/motionlabs) - **Issues**: [GitHub Issues](https://github.com/MotionEcosystem/walrus-mcp/issues) - **Email**: [hello@motionecosystem.com](mailto:hello@motionecosystem.com) --- <div align="center"> _{Built with 🦭 for the decentralized future} </div>