HybridS3
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
HybridS3
Lightweight object storage that speaks S3 (boto3/AWS SDK compatible), plain HTTP, and MCP. SQLite for metadata, flat files on disk.
Documentation: https://psyb0t.github.io/docker-hybrids3/
Table of contents
Related MCP server: hive-mcp-agent-storage
Why
Most self-hosted S3-compatible storage is built for large deployments. Distributed erasure coding, IAM policies, WORM compliance, full web consoles. Useful if you run a cloud, overkill if you just want a place to put files that a few services and AI agents can read and write.
AWS Sig V4 breaks behind reverse proxy path prefixes. Put most implementations behind nginx at /storage/, nginx strips the prefix, the server sees /bucket/key while the client signed /storage/bucket/key, and every signature check fails. hybrids3 has a path_prefix setting: set it to /storage, every route moves under it, the proxy forwards the path untouched and the signatures match.
Three interfaces, one service. boto3 works out of the box. curl with a Bearer token works. AI agents connect over MCP and get typed tools. One container, one port.
Buckets are configuration, not state. There is no API to create or delete a bucket. Buckets live in the YAML config, so you always know exactly what exists, it's version-controlled, and no surprise buckets pile up garbage.
TTL expiry is built in. Set ttl: 24h on a bucket and objects expire 24 hours after their last write. No lifecycle policies, no cron jobs.
Small enough to read in an afternoon. Thirteen Python modules.
Quick start
# get the example config, then change every key in it
wget -O config.yaml \
https://raw.githubusercontent.com/psyb0t/docker-hybrids3/main/config.example.yaml
docker run -d --name hybrids3 \
-p 127.0.0.1:8080:8080 \
-v ./config.yaml:/config/config.yaml:ro \
-v hybrids3-data:/data \
psyb0t/hybrids3
curl http://localhost:8080/healthThe container reads /config/config.yaml, keeps everything in /data and runs as UID 1000. Running the container covers Compose, upgrades and backups, and Configuration lists every setting.
Three ways in
Plain HTTP with a Bearer token. Public buckets need no token to read:
curl -X PUT http://localhost:8080/uploads/file.txt \
-H "Authorization: Bearer uploads-secret" \
--data-binary "hello"
curl http://localhost:8080/uploads/file.txtboto3, with the bucket's public_key as access key ID and its key as secret:
import boto3
from botocore.config import Config
s3 = boto3.client(
"s3",
endpoint_url="http://localhost:8080",
aws_access_key_id="uploads-id",
aws_secret_access_key="uploads-secret",
region_name="us-east-1",
config=Config(signature_version="s3v4"),
)
s3.put_object(Bucket="uploads", Key="file.txt", Body=b"hello")MCP, Streamable HTTP at /mcp/, with seven tools for uploading, downloading, listing, deleting and presigning:
{
"mcpServers": {
"hybrids3": {
"type": "streamable-http",
"url": "http://localhost:8080/mcp/"
}
}
}There is also an agent skill and plugin for Claude Code, Codex and OpenClaw; see Agent integrations.
Documentation
The full documentation lives at https://psyb0t.github.io/docker-hybrids3/.
Page | What it covers |
Tags, mounts, Compose, file ownership, upgrades, backups | |
Every | |
Bucket key pairs, the master key, public and private buckets | |
Routes, headers, status codes and error codes | |
Signature V4, boto3, aws-cli and supported operations | |
Client setup, auth layers and every tool | |
Time-limited GET and PUT links | |
MIME detection, TTL, cleanup and per-object locks | |
| |
Skill and plugins for Claude Code, Codex and OpenClaw | |
What is protected, known gaps, checklist before exposing it | |
Log format, startup errors and common failures | |
Modules and the path of a request | |
Dev container, tests, dependencies, CI and releases |
Development
All tooling runs in a sandboxed dev container, so the host needs only Docker, Make, Bash and curl.
make help # every target
make lint # flake8 + mypy
make test # production image, unit tests and the integration suite
make build # production image
make docs # build the documentation site locallyDependency changes go through make pkg-add, pkg-remove, pkg-update and pkg-upgrade, which move the supply-chain age gate in pyproject.toml together with the lockfile. Development has the details, and AGENTS.md is the guide for coding agents.
Limitations
No multipart upload, no object versioning, no ACLs beyond bucket-level public/private, no bucket creation or deletion through the API, no CORS headers, no replication and no encryption at rest. Listings stop at 1000 objects.
Sponsor
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Persistent file storage for AI agents. Save files over MCP, get a link a human can open.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides persistent storage for AI agents via MCP and REST API, enabling saving and retrieving text, code, configs, and files with full-text search, tags, version history, and GitHub backup.1MIT
- AlicenseNot gradedqualityDmaintenanceAgent-native object storage MCP server with per-agent DID isolation and x402 pay-per-byte metering in real Base USDC, enabling autonomous agents to store and retrieve objects with hot, warm, or cold retention classes.MIT
- FlicenseNot gradedqualityDmaintenanceEnables LLM agents to interact with MinIO/S3 object storage, supporting bucket and object operations like listing, reading, writing, and generating presigned URLs.1-
- AlicenseNot gradedqualityCmaintenanceEnables agents to interact with any S3-compatible storage (AWS S3, LocalStack, MinIO) via MCP, providing tools like list, read, write, delete objects and buckets.MIT