Swarm MCP Server

A Model Context Protocol (MCP) server implementation that uses Ethereum Swarm's Bee API for storing and retrieving data.

Overview

This server implements the Model Context Protocol (MCP), a standard protocol for connecting AI systems with external tools and data sources. The Swarm MCP server provides tools to upload and download text data, storing this data on the Swarm decentralized storage network using the Bee API.

Features

Upload text data to Swarm.
Download text data from Swarm.
Upload files and folders to Swarm.
Download files and folders from Swarm.
Update data on a Swarm feed.
Read latest data from a Swarm feed.
Create postage stamp batches for storage.
Get a postage stamp batch.
List postage stamp batches.
Extend storage and duration of a postage stamp batch.
Track the progress of deferred (background) uploads.
Run long-running operations as MCP tasks.
Expose every tool as an MCP prompt.

Configuration Options

Option	Type	Required	Description
`BEE_API_URL`	string	optional (unless using your own node)	The URL of the Bee API endpoint. If omitted, the default Swarm Gateway will be used: `https://api.gateway.ethswarm.org`. Example: `http://localhost:1633`.
`BEE_FEED_PK`	string	optional (cannot update feed without it)	The private key of the Swarm Feed to use. If not provided, Swarm Feed functionality will be disabled.
`AUTO_ASSIGN_STAMP`	boolean	optional	Whether to automatically assign a postage stamp if none is provided. Default value is: true. Set to false to disable automatic stamp assignment.
`DEFERRED_UPLOAD_SIZE_THRESHOLD_MB`	number	optional	Size threshold in megabytes for deferred uploads. Files larger than this size will be uploaded asynchronously. Default value is: 5 (MB).
`TASK_TTL_MS`	number	optional	Time to live of a task in milliseconds. Default value is: 1200000 (20 minutes). If the task TTL specified by the MCP client is larger than this value, that one will be used.
`PORT`	number	optional (web mode only)	Port the HTTP server listens on. Default value is: 3000.
`HOST`	string	optional (web mode only)	Host interface the HTTP server binds to. Default value is: `0.0.0.0`.

Bee Node vs. Swarm Gateway

The server detects at runtime whether BEE_API_URL points at the public Swarm Gateway or at a full Bee node, and adapts what it exposes:

Own Bee node (e.g. http://localhost:1633): all tools are available, and tools that support it can be executed as MCP tasks.
Swarm Gateway (the default when BEE_API_URL is omitted): the postage-stamp tools (create_postage_stamp, get_postage_stamp, list_postage_stamps, extend_postage_stamp) and query_upload_progress are omitted from tools/list, because the gateway does not expose those endpoints. Task execution is also disabled, so every call runs synchronously.

MCP Tools

The server provides the following MCP tools:

`create_postage_stamp`

Buy postage stamp batch based on size in megabytes and duration.

Parameters:

size: Storage capacity, e.g. 1GB, 1MB, 1KB.
duration: Duration for which the data should be stored. Time to live of the postage stamp batch, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.
label: (Optional) Sets label for the postage stamp batch.

Sample prompt:

Create new stamp with 4 days, 10 megabytes.

`get_postage_stamp`

Get a specific postage stamp batch based on batch id.

Parameters:

postageBatchId: The id of the postage stamp batch which is requested.

Sample prompt:

Give me the details for batch 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.

`list_postage_stamps`

List the available postage stamp batches.

Parameters:

leastUsed: (Optional) A boolean value that tells if postage stamp batches are sorted so least used comes first.
limit: (Optional) Limit is the maximum number of returned postage stamp batches.
minUsage: (Optional) Only list postage stamp batches with at least this usage percentage.
maxUsage: (Optional) Only list postage stamp batches with at most this usage percentage.

Sample prompt:

List my stamps.

`extend_postage_stamp`

Increase the duration (relative to current duration) or size (in megabytes) of a postage stamp batch.

Parameters:

postageBatchId: The id of the postage stamp batch for which extend is performed.
size: (Optional) Storage capacity, e.g. 1GB, 1MB, 1KB.
duration: (Optional) Duration for which the data should be stored. Time to live of the postage stamp batch, e.g. 1d - 1 day, 1w - 1 week, 1month - 1 month.

Sample prompt:

Extend 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa by 5 days.

`upload_data`

Upload text data to Swarm.

Parameters:

data: Arbitrary string to upload.
redundancyLevel: (Optional) Redundancy level for fault tolerance: 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid (higher values provide better fault tolerance but increase storage overhead). Optional, value is 0 if not requested.
postageBatchId: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.

Sample prompt:

Upload data to Swarm: Hello World!.

`download_data`

Downloads immutable data from a Swarm content address hash.

Parameters:

reference: Swarm reference hash.

Sample prompt:

Download data from Swarm: 76d133e2798d2b15db55b6c3de01303acd86e43998eab372e25c5a2115bf3f0b.

`update_feed`

Update the feed of a given topic with new data.

Parameters:

data: Arbitrary string to upload.
memoryTopic: If provided, uploads the latest data to a feed with this topic. It is the label of the memory that can be used later to retrieve the data instead of its content hash. If not a hex string, it will be hashed to create a feed topic.
postageBatchId: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.

Sample prompt:

Update the Swarm feed of Topic1 with: Message1 using postage batch id 3b3881ac37f936a4023a4562c69f1f138df8c1c24994f7b047514fbcbe9388fa.

`read_feed`

Retrieve the latest data from the feed of a given topic.

Parameters:

memoryTopic: Feed topic.
owner: (Optional) When accessing external memory or feed, ethereum address of the owner must be set..

Sample prompt:

Read the Swarm feed of Topic1.

`upload_file`

Upload a file to Swarm. Small files upload synchronously and return the reference. Large files (over the deferred-upload threshold) upload in the background: the response immediately includes the final reference (computed locally) and a tag ID for query_upload_progress; the content becomes retrievable at the reference once the upload completes. When redundancyLevel > 0, only the tag ID is returned immediately.

Parameters:

data: File content or file path.
redundancyLevel: (Optional) Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid.
postageBatchId: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.

Sample prompt:

Upload to Swarm the file: uploads/file.txt.

`upload_folder`

Upload a folder to Swarm.

Parameters:

folderPath: Path to the folder to upload.
redundancyLevel: (Optional) Redundancy level for fault tolerance (higher values provide better fault tolerance but increase storage overhead). 0 - none, 1 - medium, 2 - strong, 3 - insane, 4 - paranoid.
postageBatchId: (Optional) The postage stamp batch ID which will be used to perform the upload, if it is provided.

Sample prompt:

Upload to Swarm folder: /home/conversational-agent-client/uploads.

`download_files`

Download a file or folder from a Swarm reference and save it to disk. Handles both single files and folder manifests. The reference must be a manifest — for raw text data uploaded with upload_data, use download_data instead.

Parameters:

reference: Swarm reference hash.
filePath: (Optional) Destination folder (not a filename) to save the downloaded content into. Files from the manifest are written inside this folder under their original names. Absolute paths are recommended; relative paths resolve against the server's working directory. If omitted, files are saved into the server's current working directory. Only available in stdio mode.

Sample prompt:

Download from Swarm the file with reference ba35af06601ddf5ac3d71ee33da0db7537215a914fd6a5414b5597bb3d618bdb to folder downloads.

`query_upload_progress`

Query upload progress for a specific upload session identified with the returned Tag ID. Also returns the final Swarm reference of the upload, which is how you obtain the reference of a deferred upload_folder (a folder's reference cannot be computed up front) once processedPercentage reaches 100.

Parameters:

tagId: Tag ID returned by the upload_file and upload_folder tools to track upload progress.

Sample prompt:

Query Swarm for upload tag with id: 1.

MCP Tasks (long-running operations)

The server declares the tasks capability, so a client can ask for a slow operation to be executed as a task and poll for its result instead of holding the tool call open.

Task execution is opt-in per call: the client includes task parameters (ttl, pollInterval) in the tools/call request. If it does not, the tool runs synchronously as usual.

The following tools accept task execution (taskSupport: "optional"):

upload_file
upload_folder
download_files
create_postage_stamp
extend_postage_stamp

All other tools are declared taskSupport: "forbidden" and always run synchronously. Task execution also requires a real Bee node — see Bee Node vs. Swarm Gateway.

Supported task requests: tasks/get, tasks/result, and tasks/list (paginated with a cursor, 50 tasks per page).

Task lifetime is governed by TASK_TTL_MS (default 20 minutes); the effective TTL is the larger of that value and the one the client requested. The default poll interval is 5 seconds. Tasks are held in an in-memory store, so they do not survive a server restart.

MCP Prompts

The server also declares the prompts capability and exposes one prompt per tool, named <tool_name>_prompt (e.g. upload_data_prompt, download_files_prompt). Each prompt takes the same arguments as the corresponding tool and returns a natural-language instruction — useful for clients that surface prompts as slash commands or templates. The prompt list is generated from the tool schemas, so it always stays in sync with the tools above.

Setup

Prerequisites

Node.js 18+ installed
npm
A running Bee node or access to a public Bee gateway
A valid postage batch ID (for production use)

Installation

Clone this repository
Install dependencies:

npm ci

Configuration

You need to create a .env file with the content from .env.example. Update the environment variables with the desired values.

Tests, Linting and Formatting

npm test          # run the Jest test suite
npm run lint      # ESLint
npm run format    # Prettier, writes in place

Publishing

This server is also published to the Model Context Protocol registry as io.github.Solar-Punk-Ltd/swarm-mcp, with the npm package @solarpunkltd/swarm-mcp (stdio transport). The registry metadata lives in server.json. For the release and publishing process, see the MCP registry publishing guide.

Running the Server Locally

You can run the server locally in two different modes: stdio or web.

Stdio (Default)

This is the standard mode for direct integration with MCP clients that manage their own subprocesses.

Development (with hot-reloading):

npm run dev

Development (without building):

npm run serve

Production: First, build the project:

npm run build

Then, run the server:

npm start
# or
npm run start:stdio

Web Server (HTTP)

This runs the server as a web service on port 3000, with endpoints for HTTP.

Development (without building):

npm run serve:web

Production: First, build the project:

npm run build

Then, run the server:

npm run start:web

Docker

This project includes a Dockerfile to run the Swarm MCP server as a containerized service with HTTP transport.

Dockerfile: Builds a single image for the server, which runs on port 3000.

Building the Docker Image

To build the Docker image, run the following command from the project root:

docker build -t swarm-mcp .

Running the Docker Container

To run the server, use the docker run command. The container exposes port 3000 for HTTP.

docker run --name swarm-mcp -p 3000:3000 swarm-mcp

Configuration with Environment Variables

To configure the server, pass environment variables to the container using the -e flag. This is necessary to connect to your own Bee node or use features like Swarm Feeds.

docker run -p 3000:3000 \
  -e BEE_API_URL="http://localhost:1633" \
  -e BEE_FEED_PK="your_private_key_here" \
  -e AUTO_ASSIGN_STAMP="true" \
  -e DEFERRED_UPLOAD_SIZE_THRESHOLD_MB="5" \
  swarm-mcp

Testing with cURL

The HTTP transport is session-based, so tools/list cannot be sent on its own: every session starts with an initialize request, and the server returns the session id in the Mcp-Session-Id response header. Subsequent requests must echo that id back.

First, initialize and read the session id from the response headers (-i):

curl -i -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "curl", "version": "1.0.0" }
  }
}'

Then list the tools, passing the id from the Mcp-Session-Id header above:

curl -X POST http://localhost:3000/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-H "Mcp-Session-Id: <session-id-from-the-initialize-response>" \
-d '{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}'

A successful response contains the list of the server's tools. Send DELETE /mcp with the same header to end the session.

Note: text/event-stream in the accept header is required, and responses arrive as a server-sent event frame (event: message followed by a data: line holding the JSON-RPC payload) rather than as a bare JSON body. Requests with no session id are rejected with 400, and requests naming an unknown or ended session with 404.

Using with MCP Clients

The server supports two connection methods:

1. Web Connection (Docker)

When running the server in Docker, it operates as a web service with HTTP endpoint. To connect your MCP client, you must use: http://localhost:3000/mcp.

In your client's settings, add a new remote/custom connector and provide the appropriate URL.

Note on supported features: Functionalities that require direct access to the local file system are not available in web mode, and are only supported when running the server in stdio mode:

upload_folder is rejected outright — it always reads from the local file system.
upload_file is rejected when the data value resolves to an existing local file. The server decides this itself by checking the path; there is no flag to set. Passing raw file content as data works in both modes.
download_files is rejected when filePath is supplied. Without filePath the call succeeds, but the files are written into the working directory of the server process, not the client machine.

2. Stdio Connection (Local)

For local development or with clients that manage their own server subprocesses, you can run the server directly in stdio mode.

For detailed instructions on how to configure your MCP client for stdio, please refer to the Swarm MCP Client Setup guide.

To run the server in this mode, see the commands under the Stdio (Default) section above.

Name		Name	Last commit message	Last commit date
docs		docs
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.prettierrc		.prettierrc
Dockerfile		Dockerfile
README.md		README.md
eslint.config.mjs		eslint.config.mjs
jest.config.ts		jest.config.ts
package-lock.json		package-lock.json
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
server.json		server.json
tsconfig.json		tsconfig.json

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Swarm MCP Server

Overview

Features

Configuration Options

Bee Node vs. Swarm Gateway

MCP Tools

create_postage_stamp

get_postage_stamp

list_postage_stamps

extend_postage_stamp

upload_data

download_data

update_feed

read_feed

upload_file

upload_folder

download_files

query_upload_progress

MCP Tasks (long-running operations)

MCP Prompts

Setup

Prerequisites

Installation

Configuration

Tests, Linting and Formatting

Publishing

Running the Server Locally

Stdio (Default)

Web Server (HTTP)

Docker

Building the Docker Image

Running the Docker Container

Configuration with Environment Variables

Testing with cURL

Using with MCP Clients

1. Web Connection (Docker)

2. Stdio Connection (Local)

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`create_postage_stamp`

`get_postage_stamp`

`list_postage_stamps`

`extend_postage_stamp`

`upload_data`

`download_data`

`update_feed`

`read_feed`

`upload_file`

`upload_folder`

`download_files`

`query_upload_progress`