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 "Install 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 Serverstore 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: MinIO Storage 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
| Name | Required | Description | Default |
|---|---|---|---|
| blobId | Yes | The blob ID to delete |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action without behavioral details. It doesn't disclose if deletion is permanent, requires specific permissions, has rate limits, or what happens on success/failure, which is inadequate for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with zero waste, front-loading the core action. It's appropriately sized for a simple tool, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive tool with no annotations and no output schema, the description is incomplete. It lacks critical context like irreversible effects, error handling, or return values, leaving significant gaps in understanding the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema fully documents the 'blobId' parameter. The description adds no additional meaning beyond implying the parameter is used for deletion, meeting the baseline for high schema coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Delete') and resource ('a blob from Walrus storage'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_blob' or 'store_blob' beyond the obvious action difference, missing explicit comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing the blob ID), exclusions, or comparisons to siblings like 'list_blobs' for finding IDs, leaving usage context vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_blobC
Retrieve a blob from Walrus storage
| Name | Required | Description | Default |
|---|---|---|---|
| blobId | Yes | The blob ID to retrieve |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a retrieval operation but doesn't mention whether it requires authentication, has rate limits, returns binary data, or handles errors. For a storage tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a storage retrieval tool. It doesn't explain what 'blob' means in this context, what format the retrieved data is in, error handling, or authentication requirements. The agent lacks sufficient context to use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the single parameter 'blobId' adequately. The description doesn't add any additional meaning about parameter usage, format, or constraints beyond what the schema provides, meeting the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Retrieve') and resource ('a blob from Walrus storage'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'get_blob_info' which also retrieves blob information, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_blob_info' (for metadata) or 'list_blobs' (for listing). There's no mention of prerequisites, error conditions, or typical use cases, leaving the agent with insufficient context for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_blob_infoB
Get information about a blob (size, availability, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| blobId | Yes | The blob ID to get information about |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool retrieves information, implying a read-only operation, but doesn't disclose behavioral traits such as authentication needs, rate limits, error conditions, or what 'availability' entails. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Get information about a blob') and adds specific details ('size, availability, etc.') without waste. Every word earns its place, making it appropriately sized and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, read-only implied), 100% schema coverage, and no output schema, the description is minimally adequate. It covers the basic purpose but lacks context on behavioral aspects (e.g., permissions, errors) and doesn't explain return values. Without annotations, it should do more to compensate, but the simplicity keeps it from being severely incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, with the single parameter 'blobId' documented in the schema. The description adds no additional meaning about the parameter beyond what the schema provides (e.g., format examples or constraints). With high schema coverage, the baseline score of 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('blob'), specifying the type of information retrieved ('size, availability, etc.'). It distinguishes from siblings like 'get_blob' (likely retrieves content) and 'list_blobs' (lists multiple), but doesn't explicitly contrast them. The purpose is specific but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_blob' or 'list_blobs'. It implies usage for retrieving metadata about a specific blob, but offers no explicit context, exclusions, or prerequisites. This leaves the agent to infer usage from the tool name and description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_blobsC
List stored blobs
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of blobs to list (default: 10) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'List stored blobs' but does not reveal key traits: whether it's read-only (implied but not explicit), how results are ordered or paginated, if authentication is required, or potential rate limits. For a list operation with zero annotation coverage, this leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at three words, with zero wasted text. It is front-loaded and directly states the tool's action without unnecessary elaboration, making it efficient for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete for a list tool. It does not explain return values (e.g., blob names, metadata, or pagination tokens), error conditions, or dependencies. While the schema covers the single parameter well, the overall context for effective tool use is insufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the 'limit' parameter fully documented. The description does not add any meaning beyond the schema, as it mentions no parameters. According to the rules, when schema coverage is high (>80%), the baseline score is 3 even without parameter info in the description, which applies here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List stored blobs' clearly states the verb ('List') and resource ('stored blobs'), making the purpose understandable. However, it lacks specificity about scope (e.g., all blobs vs. filtered) and does not distinguish it from sibling tools like 'get_blob' or 'get_blob_info', which might retrieve individual blobs or metadata. This vagueness prevents a higher score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools like 'get_blob' (for retrieving a specific blob) or 'get_blob_info' (for metadata), nor does it specify contexts such as browsing vs. targeted access. Without any usage instructions, the agent must infer from tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
store_blobB
Store a blob in Walrus decentralized storage
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes | Base64 encoded data or file path to store | |
| epochs | No | Number of epochs to store the blob (default: 5) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. While 'Store' implies a write operation, it fails to describe critical behaviors like whether storage is permanent or reversible, authentication requirements, rate limits, or error conditions. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a write operation with no annotations and no output schema), the description is incomplete. It lacks details on behavioral traits, error handling, or return values, which are essential for an agent to use this tool effectively in a decentralized storage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, documenting both parameters (data as base64/file path, epochs with default). The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline score of 3 without compensating for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Store') and resource ('a blob in Walrus decentralized storage'), making the purpose immediately understandable. It distinguishes this tool from its siblings (delete_blob, get_blob, etc.) by specifying it's for storage rather than retrieval or deletion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like list_blobs or get_blob. It lacks context about prerequisites, such as whether data must be pre-processed or if there are storage limits, leaving the agent without usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
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
Persistent agent memory paid per call via x402 USDC. Your wallet is your private memory namespace.
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
- AlicenseBqualityDmaintenanceEnables AI assistants to manage MinIO object storage through comprehensive bucket operations, file uploads/downloads, batch processing, permissions management, and URL generation. Supports both automatic and manual connection modes with flexible authentication options.19202MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to autonomously manage files on the Filecoin decentralized network through folder management, file uploads, and AI-powered semantic search. Provides seamless integration with Filecoin storage through simple MCP tool calls.2MIT
- AlicenseNot gradedqualityCmaintenanceProvides 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.1612MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Motion-Labs-Sui/walrus-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server