# s3-mcp-connector [Health: Active]
**Category:** ๐ป Developer Tools
**Repository:** https://github.com/FerhatDundar/s3-mcp-connector
**GitHub Stars:** 0
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/s3-mcp-connector
## Description
MCP server for Amazon S3 and S3-compatible endpoints (LocalStack, MinIO). Single Go binary.
## Claude Desktop Quick Installation
Heuristic fallback โ verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):
```json
"mcpServers": {
"s3-mcp-connector": {
"command": "npx",
"args": ["-y","s3-mcp-connector"]
}
}
```
## Documentation & README
# ๐ชฃ s3-mcp-connector
**Talk to Amazon S3 โ or LocalStack, MinIO, any S3-compatible store โ from an MCP-speaking agent.**
[](https://github.com/FerhatDundar/s3-mcp-connector/actions/workflows/ci.yml)
[](https://github.com/FerhatDundar/s3-mcp-connector/actions/workflows/codeql.yml)
[](https://github.com/FerhatDundar/s3-mcp-connector/releases/latest)
[](https://registry.modelcontextprotocol.io/?q=s3-mcp-connector)
[](https://go.dev/)
[](LICENSE)
[](https://localstack.cloud/)
[](https://modelcontextprotocol.io/)
[](https://www.conventionalcommits.org/)
[](CONTRIBUTING.md)
---
A single static Go binary that speaks the [Model Context Protocol](https://modelcontextprotocol.io/)
and exposes 8 tools for working with S3: list buckets, list/read/write/delete
objects, create/delete buckets. Point it at real AWS or at a local
LocalStack/MinIO instance with one environment variable โ same binary,
same tools, zero code changes.
No Python, no `uv`, no runtime dependency to install โ just a binary and
an `.mcp.json`.
## โจ Why this exists
> An agent that can only *talk about* your S3 buckets isn't that useful.
> This gives it hands: it can look inside a bucket, read a config file out
> of it, drop a report back in, or clean up a stale prefix โ safely, with
> guardrails on size and destructive actions built in.
## ๐งฐ Tools
| Tool | What it does | Write? |
|---|---|:---:|
| `s3_list_buckets` | List buckets visible to the credentials | |
| `s3_list_objects` | List objects in a bucket, optional prefix, paginated | |
| `s3_head_object` | Object metadata (size, type, ETag) without downloading | |
| `s3_get_object` | Read an object's content โ text or base64, size-capped | |
| `s3_put_object` | Write a small text/base64 object (โค 5 MB) | โ๏ธ |
| `s3_delete_object` | Delete one object | ๐๏ธ destructive |
| `s3_create_bucket` | Create a bucket | โ๏ธ |
| `s3_delete_bucket` | Delete an *empty* bucket | ๐๏ธ destructive |
Every tool accepts an optional `response_format`: `markdown` (default,
pretty tables for a chat UI) or `json` (for programmatic use).
`s3_get_object` auto-detects text vs. binary content and caps output at
**200,000 bytes** by default (raise via `max_bytes`, hard cap
**5,000,000**) โ it's built for reading configs, logs, and small data
files, not bulk transfer. Reach for the AWS CLI or SDK directly for large
objects.
## ๐ Quickstart
**Fastest path:** grab a prebuilt bundle from the [latest release](https://github.com/FerhatDundar/s3-mcp-connector/releases/latest) โ
download `s3-mcp-connector-plugin---.zip`, unzip it,
and point Cowork/Claude at the `plugin/` folder inside (see step 4 of
[SETUP.md](SETUP.md)). No Go toolchain required.
**From source:**
```bash
# 1. Build
cd go-server
go mod tidy
go build -o s3-connector-server .
cp s3-connector-server ../plugin/servers/go/
# 2. Spin up LocalStack to test against (no AWS account needed)
cd ..
docker compose up -d
# 3. Point the connector at it
export AWS_ACCESS_KEY_ID=test
export AWS_SECRET_ACCESS_KEY=test
export AWS_REGION=us-east-1
export S3_ENDPOINT_URL=http://localhost:4566
export S3_FORCE_PATH_STYLE=true
./go-server/s3-connector-server # serves MCP over stdio
```
Or `make build && make localstack-up` โ see the [Makefile](Makefile) for
every shortcut (`test`, `vet`, `fmt`, `lint`, `tidy`, `localstack-down`).
Full walkthrough โ including wiring this up as a Claude/Cowork plugin and
switching from LocalStack to real AWS โ is in **[SETUP.md](SETUP.md)**.
## ๐ Configuration
Everything is environment variables, passed through by the plugin's
`.mcp.json`:
| Variable | Purpose | Default |
|---|---|---|
| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS credentials. Any non-empty values work against LocalStack. | โ |
| `AWS_REGION` | Region to use. | `us-east-1` |
| `S3_ENDPOINT_URL` | Custom endpoint. Leave unset for real AWS. | *(unset)* |
| `S3_FORCE_PATH_STYLE` | `true` for LocalStack/MinIO (path-style addressing). | `false` |
## ๐งช Quality bar
This isn't a toy script โ it's got the same checks you'd expect from a
production Go service:
- โ
**Unit tests** for every input-validation path (`go test ./...`)
- โ
**`go vet`** + **`gofmt`** clean
- โ
**[golangci-lint](https://golangci-lint.run/)** (govet, staticcheck, errcheck, gosec, and more)
- โ
**[govulncheck](https://go.dev/blog/vuln)** โ no known vulnerabilities in the dependency graph
- โ
**[CodeQL](https://codeql.github.com/)** static security analysis on every push
- โ
**End-to-end verified against real LocalStack** โ every tool
(create/delete bucket, put/get/head/list/delete object, and the 404
error path) was exercised against a live S3-compatible service, not
mocks
- โ
**[Dependabot](.github/dependabot.yml)** keeps Go modules and Actions current
All of it runs in [CI](.github/workflows/ci.yml) on every push and PR.
## ๐ท๏ธ Releases & versioning
Versions follow [semver](https://semver.org/) and are cut automatically by
[release-please](https://github.com/googleapis/release-please) from
[Conventional Commits](https://www.conventionalcommits.org/) on `main`:
- `fix: ...` โ patch (`v0.1.0` โ `v0.1.1`)
- `feat: ...` โ minor (`v0.1.1` โ `v0.2.0`)
- `feat!: ...` / `BREAKING CHANGE:` footer โ major (`v0.2.0` โ `v1.0.0`)
Every merged PR updates a standing **"chore(main): release vX.Y.Z"** PR
with an auto-generated [CHANGELOG.md](CHANGELOG.md). Merging that PR:
1. tags the release and publishes it on GitHub
2. builds and attaches zipped, ready-to-install plugin bundles for
linux/darwin/windows ร amd64/arm64
3. regenerates `server.json` from those exact assets (fresh version +
SHA-256 hashes) and publishes it to the
[official MCP Registry](https://registry.modelcontextprotocol.io/) via
`mcp-publisher`, authenticated with GitHub OIDC โ no stored secrets
See [.github/workflows/release-please.yml](.github/workflows/release-please.yml)
and [.github/workflows/publish-mcp-registry.yml](.github/workflows/publish-mcp-registry.yml)
(also runnable by hand for an existing tag via `workflow_dispatch`).
## ๐ Layout
```
s3-mcp-connector/
โโโ README.md โ you are here
โโโ SETUP.md โ step-by-step setup guide (LocalStack + real AWS)
โโโ CONTRIBUTING.md โ how to contribute
โโโ CODE_OF_CONDUCT.md
โโโ SECURITY.md โ vulnerability reporting
โโโ CODEOWNERS
โโโ LICENSE โ MIT
โโโ Makefile โ build / test / lint / localstack shortcuts
โโโ docker-compose.yml โ LocalStack, for local testing
โโโ .golangci.yml โ lint rules
โโโ release-please-config.json โ semver/changelog automation config
โโโ .release-please-manifest.json
โโโ server.json โ MCP Registry manifest (regenerated fresh per release by CI)
โโโ scripts/
โ โโโ render-server-json.sh โ rebuilds server.json from a release's zip assets
โโโ .github/
โ โโโ workflows/
โ โ โโโ ci.yml โ build, vet, test, lint, govulncheck
โ โ โโโ codeql.yml โ security scanning
โ โ โโโ pr-title.yml โ Conventional Commits PR title check
โ โ โโโ release-please.yml โ version PRs, tagging, GitHub releases
โ โ โโโ publish-mcp-registry.yml โ publishes server.json to the MCP Registry
โ โ โโโ rebuild-release-assets.yml โ manual re-attach fallback
โ โโโ ISSUE_TEMPLATE/
โ โโโ PULL_REQUEST_TEMPLATE.md
โ โโโ dependabot.yml
โโโ go-server/ โ the MCP server source
โ โโโ main.go
โ โโโ main_test.go
โ โโโ go.mod / go.sum
โ โโโ README.md
โโโ plugin/ โ installable Cowork/Claude plugin
โโโ .claude-plugin/plugin.json
โโโ .mcp.json โ holds credentials locally โ never commit real ones
โโโ servers/go/ โ compiled binary goes here
```
## ๐ค Contributing
PRs and issues are very welcome โ see **[CONTRIBUTING.md](CONTRIBUTING.md)**
for the full guide (setup, coding conventions, how to add a new tool) and
the **[Code of Conduct](CODE_OF_CONDUCT.md)**.
`main` is protected: every change, including the maintainer's, lands via
pull request with CI green. PR titles must follow
[Conventional Commits](https://www.conventionalcommits.org/) โ that's what
drives the automatic versioning above.
Found a security issue? Please follow **[SECURITY.md](SECURITY.md)**
instead of opening a public issue.
## ๐ License
[MIT](LICENSE) ยฉ Ferhat Dundar