HybridS3 — Claude Code MCP server: self-hosted S3 for agents
A self-hosted object store that speaks S3, plain HTTP and MCP. Handy when an agent needs somewhere on your own box to read and write files.
Open on GitHubWhat HybridS3 does
HybridS3 ships as the psyb0t/hybrids3 container and exposes one dataset through three interfaces. AWS SDK and boto3 talk to it like any S3 endpoint, curl uses plain HTTP, and AI agents connect over MCP to get structured tool definitions. Metadata lives in SQLite; the objects themselves sit on disk as flat files.
Buckets are declared in config.yaml. There is no API to create or delete them, so the config is the whole truth and nothing accumulates behind your back. Per bucket you set keys, a public flag, ttl and max_file_size. A master_key works across every bucket and is the only credential that can list them all.
The container wants its config at /config/config.yaml, data at /data, and listens on port 8080 as UID 1000. Running it behind nginx on a subpath? Set path_prefix, otherwise AWS Sig V4 verification fails: the proxy strips the prefix and the server sees a different path than the one that was signed. Leave it out and routes are served from the root.
What it helps with
- give an agent file storage without a cloud account
- stand up an S3-compatible backend for
boto3in minutes - serve uploaded files publicly while keeping the rest behind a key
- auto-delete temporary objects with
ttl - cap upload size per bucket so huge files bounce
Example prompts for the agent
- Connect to the HybridS3 MCP server and list the tools it exposes
- Upload
report.pdfto theuploadsbucket through HybridS3 - Show me every object in the
permanentbucket
How to install HybridS3
Install
The MCP registry has no launch command for it: see the repository README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about HybridS3
How do I install HybridS3 in Claude Code?
Fetch the example config with wget -O config.yaml https://raw.githubusercontent.com/psyb0t/docker-hybrids3/master/config.example.yaml, edit your keys and buckets, then start the container: docker run -d --name hybrids3 -p 8080:8080 -v ./config.yaml:/config/config.yaml:ro -v hybrids3-data:/data psyb0t/hybrids3. Check it with curl http://localhost:8080/health.
What does HybridS3 do?
It stores objects and serves them over an S3-compatible API, plain HTTP and MCP. Agents connecting via MCP get structured tools for reading and writing files.
How is HybridS3 different from a regular S3 store?
Buckets live in a YAML config file — no API creates or deletes them. TTL expiry is built into the server, so you don't need lifecycle policies or a cron job.
