Storacha MCP Storage Server

A Model Context Protocol (MCP) server implementation for Storacha storage, enabling AI applications to interact with decentralized storage through a standardized interface.

Features

File Operations
- Upload files to Storacha's decentralized storage network
- Retrieve files via Storacha's HTTP gateway
Identity Management
- Get the DID key of the Storacha agent
Dual Transport Modes
- HTTP with Server-Sent Events (SSE) for real-time communication
- Stdio transport for local integrations
Standardized Interface
- MCP-compliant API for tool discovery and invocation
- JSON-RPC message handling
Security
- Bearer Token
- CORS configuration
- Input validation
- Secure error handling

Usa Cases

Document Storage & Analysis: Securely upload and retrieve Blob documents.
Long-term Structured Data Storage: Maintain structured data storage optimized for longevity and accessibility.
Data Sharing Between Agents and Systems: Easily share data across multiple agents and diverse systems using CIDs (Content Identifiers), enabling decentralized, verifiable, and efficient data exchange.
Application Integration: Seamlessly integrate Storacha storage retrieval into applications via the Model Context Protocol.
AI Model Development: Support AI models by providing reliable access to external datasets stored in Storacha.
LLM Integration: Enhance large language models (LLMs) by connecting directly with Storacha Storage for seamless data access.
Web Application Backups: Reliably store backup copies of web applications for disaster recovery.
Machine Learning Datasets: Efficiently manage and access large datasets used in machine learning workflows.

Installation

Clone the repository
git clone https://github.com/storacha/mcp-storage-server.git cd mcp-storage-server
Install dependencies
pnpm install
Create a .env file
cp .env.example .env
Configure the server using the following environment variables
# MCP Server Configuration MCP_SERVER_PORT=3001 # Optional: The port the server will listen on (default: 3001) MCP_SERVER_HOST=0.0.0.0 # Optional: The host address to bind to (default: 0.0.0.0) MCP_CONNECTION_TIMEOUT=30000 # Optional: The connection timeout in milliseconds (default: 30000) MCP_TRANSPORT_MODE=stdio # Optional: The transport mode to use (stdio or sse) (default: stdio) # Security SHARED_ACCESS_TOKEN= # Optional: Set this to require authentication for uploads # Storage Client Configuration PRIVATE_KEY= # Required: The Storacha Agent private key that is authorized to upload files DELEGATION= # Optional: The base64 encoded delegation that authorizes the Agent owner of the private key to upload files. If not set, MUST be provided for each upload request. GATEWAY_URL=https://storacha.link # Optional: Custom gateway URL for file retrieval (default: https://storacha.link) # File Limits MAX_FILE_SIZE=104857600 # Optional: Maximum file size in bytes (default: 100MB)

Starting the Server

Option 1 - Run the Stdio Server (recommended for local server communication)

pnpm start:stdio

Option 2 - Run the SSE Server (recommended for remote server communication)

pnpm start:sse

MCP Client Integration (stdio mode)

Connect to the MCP Server

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Create the transport for communication
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
  env: {
    ...loadEnvVars(),
    MCP_TRANSPORT_MODE: 'stdio',
  },
});

// Instantiate the MCP client
client = new Client(
  {
    name: 'test-client',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Connect to the server
await client.connect(transport);

List Tools

const response = await client.listTools();
console.log(response.tools.map(tool => tool.name));
// output: ['identity', 'retrieve', 'upload']

Get the Agent's DID Key

// Get the agent's DID key
const response = await client.callTool({
  name: 'identity',
  arguments: {}, // Send an empty object
});
console.log('Agent DID:', JSON.parse(response.content[0].text));
// output:  {"id":"did:key:z6MkjiNpY1QhuULQUkF5thrDbVz2fZwg49zYMg4a7zY1KDr9"}

Upload a file

// Upload a file to the storage space defined in the delegation set in the MCP Server
const fileBuffer = new Uint8Array([1, 2, 3]);
const base64File = Buffer.from(fileBuffer).toString('base64');
const result = await client.invoke('upload', {
  file: base64File,
  name: 'example.txt',
  type: 'text/plain',
});
// output: {"root":"bafk...123","rootURL":"https://storacha.link/ipfs/bafk...123","files":[{"name":"test.txt","type":"text/plain","url":"https://storacha.link/ipfs/bafk...123/test.txt"}]}

Upload a file using a custom delegation

// Upload a file to the storage space defined in the delegation set in the upload request
const result = await client.invoke('upload', {
  file: base64File,
  name: 'example.txt',
  type: 'text/plain',
  delegation: base64Delegation,
});

Read the step-by-step guide to learn how to create a delegation using the CLI.

Testing with MCP Inspector

The MCP Inspector provides a visual interface for testing and debugging MCP servers. To test the Storacha MCP server:

Start the MCP Inspector

pnpm inspect:stdio

Start the Storacha MCP server

pnpm start:stdio

Connect to your server
- Open the Browser and access the Inspector UI at http://localhost:5173/#tools
- Enter the server URL (e.g., http://localhost:3001)
- The Inspector will automatically discover available tools
- You can test the upload and retrieve tools directly from the interface

Debugging Tips

Check the server logs for connection issues
Verify environment variables are set correctly
Ensure the server is running in SSE or Stdio mode for Inspector compatibility

Development

Project Structure

/
├── src/
│   ├── core/
│   │   ├── server/
│   │   │   ├── index.ts           # Main server entry point
│   │   │   ├── config.ts          # Server configuration
│   │   │   ├── types.ts           # TypeScript type definitions
│   │   │   ├── tools/             # MCP tools implementation
│   │   │   │   ├── index.ts       # Tool registration
│   │   │   │   ├── upload.ts      # Upload tool
│   │   │   │   ├── retrieve.ts    # Retrieve tool
│   │   │   │   └── identity.ts    # Identity tool
│   │   │   └── transports/        # Transport implementations
│   │   │       ├── sse.ts         # SSE transport
│   │   │       └── stdio.ts       # Stdio transport
│   │   └── storage/               # Storage client implementation
│   │       ├── client.ts          # Storage client
│   │       ├── config.ts          # Storage configuration
│   │       ├── types.ts           # Storage types
│   │       └── utils.ts           # Storage utilities
├── test/
│   ├── core/
│   │   ├── server/
│   │   │   ├── config.test.ts     # Configuration tests
│   │   │   ├── index.test.ts      # Server tests
│   │   │   ├── tools/             # Tool tests
│   │   │   └── transports/        # Transport tests
│   │   └── storage/               # Storage tests
│   ├── integration/               # Integration tests
│   └── setup.ts                   # Test setup
├── .env.example                   # Example environment variables
├── .eslintrc.json                 # ESLint configuration
├── .prettierrc                    # Prettier configuration
├── .husky/                        # Git hooks
│   └── pre-commit                 # Pre-commit hook
├── package.json                   # Project dependencies and scripts
├── tsconfig.json                  # TypeScript configuration
└── README.md                      # Project documentation

Building

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT or Apache 2 License

Support

For support, please visit Storacha Support or open an issue in this repository.