HybridS3 MCP server
Commit Nov 10, 2026Provides a lightweight S3-compatible object storage service that allows AI agents to upload, download, list, delete, and presign files via MCP.
Also known as psyb0t/docker-hybrids3, docker-hybrids3
- Stars
- 5
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.3.10
- Last commit
- Nov 10, 2026
- License
- WTFPL
What is HybridS3 MCP?
HybridS3 provides a lightweight S3-compatible object storage service that allows AI agents to upload, download, list, delete, and presign files via MCP.
Summary generated from the project's README
About HybridS3 MCP server
HybridS3 provides a lightweight object storage service designed specifically for AI agents and small-scale services. It functions as an S3-compatible system that uses SQLite for metadata and stores files as flat files on disk. Users can deploy it via a single Docker container, making it an ideal alternative to heavy distributed storage systems when you only need a simple place to store and retrieve files.
Developers can interact with the service through three distinct interfaces: the S3 API using boto3, plain HTTP with Bearer tokens, or the Model Context Protocol. When using MCP, agents connect via a streamable-http setup to access seven specific tools for managing files. The system uses a YAML configuration file to define buckets, ensuring that storage structure is version-controlled and predictable rather than managed through API calls.
This server includes built-in features like TTL expiry, where objects automatically disappear after a set duration. It also handles complex networking scenarios through a path_prefix setting, which prevents signature failures when running behind reverse proxies like nginx.
What you can do with it
- 1Automate temporary file storageYou can configure buckets to automatically delete files after a specific amount of time to prevent storage bloat.
- 2Integrate with standard Python scriptsDevelopers can use the boto3 library to interact with the storage using standard AWS SDK patterns.
- 3Deploy behind a reverse proxyThe service can be configured to work correctly with nginx by adjusting the path prefix to match signed requests.
Written from the project's README. Every use case is checked against a quote from it.
How to install HybridS3 MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall HybridS3 MCP in Claude Code
$ claude mcp add docker-hybrids3 -- docker run -i --rm docker.io/psyb0t/hybrids3:v0.3.10Install HybridS3 MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"docker-hybrids3": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/hybrids3:v0.3.10"
]
}
}
}Install HybridS3 MCP in VS Code
.vscode/mcp.json
{
"servers": {
"docker-hybrids3": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/hybrids3:v0.3.10"
]
}
}
}Install HybridS3 MCP in VS Code CLI
$ code --add-mcp '{"name":"docker-hybrids3","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/psyb0t/hybrids3:v0.3.10"]}'Install HybridS3 MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"docker-hybrids3": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/hybrids3:v0.3.10"
]
}
}
}Install HybridS3 MCP in Codex
$ codex mcp add docker-hybrids3 -- docker run -i --rm docker.io/psyb0t/hybrids3:v0.3.10Install HybridS3 MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.docker-hybrids3] command = "docker" args = ["run", "-i", "--rm", "docker.io/psyb0t/hybrids3:v0.3.10"]
Install HybridS3 MCP in Gemini CLI
$ gemini mcp add -s user docker-hybrids3 docker -- run -i --rm docker.io/psyb0t/hybrids3:v0.3.10Install HybridS3 MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"docker-hybrids3": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/psyb0t/hybrids3:v0.3.10"
]
}
}
}Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)WTFPL is not OSI-approvedFinding
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubHybridS3
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
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/health
The 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.txt
boto3, 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 |
|---|---|
| Running the container | Tags, mounts, Compose, file ownership, upgrades, backups |
| Configuration | Every config.yaml setting with defaults and formats |
| Keys and access | Bucket key pairs, the master key, public and private buckets |
| HTTP API | Routes, headers, status codes and error codes |
| S3 API | Signature V4, boto3, aws-cli and supported operations |
| MCP server | Client setup, auth layers and every tool |
| Presigned URLs | Time-limited GET and PUT links |
| Storage, expiry and locking | MIME detection, TTL, cleanup and per-object locks |
| Behind a reverse proxy | path_prefix, nginx and https presigned URLs |
| Agent integrations | Skill and plugins for Claude Code, Codex and OpenClaw |
| Security | What is protected, known gaps, checklist before exposing it |
| Troubleshooting | Log format, startup errors and common failures |
| Architecture | Modules and the path of a request |
| Development | 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 locally
Dependency 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
HybridS3 MCP questions
How do I add HybridS3 MCP to Claude Code?
Run claude mcp add docker-hybrids3 -- docker run -i --rm docker.io/psyb0t/hybrids3:v0.3.10 in your terminal. Add --scope user to make it available in every project.
How do I add HybridS3 MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can I create or delete buckets using the API?
No, buckets are managed through a YAML configuration file rather than an API to ensure they are version-controlled.
Does HybridS3 support automatic file expiration?
Yes, you can set a TTL (Time To Live) on a bucket to automatically expire objects after a specified duration.
How do I use HybridS3 with AWS SDKs?
It is compatible with boto3 and the AWS SDK; use the bucket's public_key as the access key ID and its key as the secret.