# HybridS3

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 5
- Author: psyb0t
- License: WTFPL · policy=link-only · description only; the file stays with the author
- Source: https://github.com/psyb0t/docker-hybrids3
- Updated: 2026-10-19
- HTML: https://affpapa.org/en/nevibecode/mcp/hybrids3

## What it 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.

## Requirements
- Needs: Docker
- Works with: Docker

## Install

### Claude Code (native platform)

**Install**
- The MCP registry has no launch command for it: see the repository README

## When to use it
- give an agent file storage without a cloud account
- stand up an S3-compatible backend for `boto3` in 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
- Connect to the HybridS3 MCP server and list the tools it exposes
- Upload `report.pdf` to the `uploads` bucket through HybridS3
- Show me every object in the `permanent` bucket

## Similar
- [backup-recovery](https://affpapa.org/en/nevibecode/skills/backup-recovery.md) — skill · 406 installs
- [Backblaze B2 MCP Server](https://affpapa.org/en/nevibecode/mcp/backblaze-b2-mcp-server.md) — MCP server · ★ 45
- [troubleshooting-s3-files](https://affpapa.org/en/nevibecode/skills/troubleshooting-s3-files.md) — skill · 6300 installs
- [digitalocean-storage](https://affpapa.org/en/nevibecode/skills/digitalocean-storage.md) — skill · 403 installs
- [aws-s3](https://affpapa.org/en/nevibecode/skills/aws-s3.md) — skill · 345 installs
- [file-storage](https://affpapa.org/en/nevibecode/skills/file-storage.md) — skill · 3100 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md