Storacha MCP Storage Server

Storacha MCP Storage Server provides a standardized Model Context Protocol interface for Storacha hot storage, enabling AI applications to securely store and retrieve files with verifiable, decentralized data exchange using IPFS and CIDs. You can integrate this MCP server with agent frameworks to support data-backed AI workflows and resilient backups.

How to use

You use the Storacha MCP Storage Server by running the local MCP server and configuring your MCP client to connect either through the local stdio transport or via REST. Once connected, you can store files and retrieve them later using Content Identifiers (CIDs), enabling secure data sharing between agents and systems.

How to install

Prerequisites: Node.js installed on your machine and a terminal access to run commands. You also need pnpm for dependency installation.

1. Clone the project and navigate into the directory.

git clone https://github.com/storacha/mcp-storage-server.git && cd mcp-storage-server

2. Install dependencies using pnpm.

pnpm install

3. Generate keys and a delegation to grant the agent permission to store data.

Install the CLI, login, create a Space, generate a private key, and create a delegation.

npm install -g @web3-storage/w3cli

w3 login

Output:

? How do you want to login?
  Via Email
❯ Via GitHub

Select Via GitHub and authenticate with your GitHub account.

w3 space create <your_space_name>

Replace <your_space_name> with a name for your new Space. Save the recovery key.

w3 key create

Output:

AgentId: did:key:z6MkhMZRW2aoJ6BQwkpMSJu68Jgqkz1FTpr1p69cpnN43YWG
PrivateKey: LMgCYLkvOc8Sm0mOL4cWFLxsWP0ZPEYrLxcQqsV93/s5RLje0BKx05muAse1Hkvh+sxUW38OcHtpiN1zxfpTJ4ht4jxV0=

w3 delegation create <agent_id> \
 --can 'store/add' \
 --can 'filecoin/offer' \
 --can 'upload/add' \
 --can 'space/blob/add' \
 --can 'space/index/add' --base64

Replace <agent_id> with the AgentId from the previous step. This grants the Agent permission to store files into the Space.

## Configure the MCP Client

Next, configure your MCP client (such as Cursor) to use Storacha MCP Storage Server. You provide a configuration JSON that informs the client how to start and connect to the server.

The following example shows a local stdio-based MCP server configuration and a REST-based HTTP configuration. These blocks should be placed in your MCP client configuration to enable both local and REST access.

{ "mcpServers": { "storacha-storage-server": { "command": "node", "args": ["./dist/index.js"], "env": { "MCP_TRANSPORT_MODE": "stdio", "PRIVATE_KEY": "<agent_private_key>", "DELEGATION": "<base64_delegation>" }, "shell": true, "cwd": "./" } } }

## REST mode and cloud hosting

If you want to expose the storage server via REST for MCP.so cloud hosting or other HTTP-based MCP clients, you can configure a REST endpoint.

{ "mcpServers": { "storacha-storage-server-rest": { "url": "http://localhost:3001/rest" } } }

## Notes on usage and behavior

Use the stdio transport for local development and testing, or REST mode for cloud deployments. The server supports the standard MCP flow for initiating a Space, generating a Private Key, and creating a delegation that authorizes file uploads. When starting your client, provide the required PRIVATE\_KEY and DELEGATION values to authorize storage actions.

## Examples of operations

Upload a blob to Storacha with a filename that helps the system detect the MIME type, and optionally publish to Filecoin.

Retrieve a stored file by CID and filename, using various acceptable path formats such as CID/filename, /ipfs/CID/filename, or ipfs://CID/filename.

Ask for the identity of the connected Storacha Agent to verify the DIDKey used for storage actions.

## Available tools

### upload

Upload a file to Storacha Network. Provide base64-encoded content along with a filename for MIME type detection and optional Filecoin publishing.

### retrieve

Retrieve a file by providing a path like CID/filename, /ipfs/CID/filename, or ipfs://CID/filename. Supports optional multiformat base64 encoding.

### identity

Return the DIDKey of the Storacha Agent loaded from the private key storage configuration.