Walrus MCP Server
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Walrus MCP Server store this document in Walrus for 10 epochs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
š¦ 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
Related MCP server: Filecoin Onchain Cloud MCP
š 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:
{
"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 |
| 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).
āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā āāāāāāāāāāāāāāāāāāā
ā 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.jsonTool 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.spacePublisher:
https://publisher-devnet.walrus.spaceSystem 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.spaceStorage 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 devContributing
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
Available Tools
5 toolsdelete_blobC
Delete a blob from Walrus storage
Inputs: blobId (required).
get_blobC
Retrieve a blob from Walrus storage
Inputs: blobId (required).
get_blob_infoB
Get information about a blob (size, availability, etc.)
Inputs: blobId (required).
list_blobsC
List stored blobs
Inputs: limit.
store_blobB
Store a blob in Walrus decentralized storage
Inputs: data (required), epochs.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogā¦
TDQS
Scored across 5 tools
Every tool has a clearly distinct purpose with no ambiguity: delete_blob removes blobs, get_blob retrieves blob content, get_blob_info provides metadata, list_blobs enumerates available blobs, and store_blob uploads new blobs. The actions (delete, get, get_info, list, store) are mutually exclusive and target the same resource type consistently.
All tools follow a consistent verb_noun pattern with snake_case naming: delete_blob, get_blob, get_blob_info, list_blobs, and store_blob. The verbs are clear and predictable, and the noun 'blob' (or 'blobs') is used uniformly across all tools.
With 5 tools, this server is well-scoped for decentralized blob storage operations. Each tool earns its place by covering essential CRUD-like functions (store, get, delete, list) plus metadata retrieval, without being overly sparse or bloated for the domain.
The tool set provides complete lifecycle coverage for blob storage: store_blob for creation, get_blob for retrieval, get_blob_info for metadata, list_blobs for enumeration, and delete_blob for removal. There are no obvious gaps, and agents can perform all core operations without dead ends.
Maintenance
Related MCP Connectors
Private, permanent encrypted storage for AI agents. Paid per call in USDC via x402.
S3 storage and Solana/Base/Ethereum health checks for AI agents, paid per call via x402.
Encrypted A2A object storage for autonomous agent state and artifacts
Searchable storage for AI agents: store, find, read and trust artifacts shared between agents.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI applications to interact with decentralized storage through a standardized Model Context Protocol interface, allowing file uploads, retrievals, and identity management.13Apache 2.0
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with seamless access to Filecoin's decentralized storage network for persistent file storage and dataset management. It features automatic payment handling, CDN support, and cost estimation tools for efficient storage operations.22 npm12MIT

MEFS MCP Serverofficial
AlicenseAqualityDmaintenanceProvides decentralized storage for AI agents, enabling them to save generated content to MEFS and retrieve data via content identifiers.211 npm1MIT- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to interact with Sui Network through tools for balance checks, transfers, swaps, staking, and more.16Apache 2.0