Skip to main content
Glama

🦭 Walrus MCP Server

MCP Server for Walrus Decentralized Storage Protocol

Built with ā¤ļø by Motion Labs

License: MIT Node.js Version TypeScript

🌐 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

  1. Clone the repository

    git clone https://github.com/MotionEcosystem/walrus-mcp.git
    cd walrus-mcp
  2. Install dependencies

    npm install
  3. 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

šŸ—ļø 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

  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:

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 file for details.

šŸ¤ Support


Available Tools

5 tools
delete_blobC

Delete a blob from Walrus storage

ParametersJSON Schema
NameRequiredDescriptionDefault
blobIdYesThe blob ID to delete

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
blobIdYesThe blob ID to retrieve

TDQS

C2.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.)

ParametersJSON Schema
NameRequiredDescriptionDefault
blobIdYesThe blob ID to get information about

TDQS

B3.1/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMaximum number of blobs to list (default: 10)

TDQS

C2.7/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose3/5

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.

Usage Guidelines2/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
dataYesBase64 encoded data or file path to store
epochsNoNumber of epochs to store the blob (default: 5)

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines2/5

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

A3.5/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    Enables 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.
    19
    20
    2
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables 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.
    2
    MIT

Latest Blog Posts

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