{
  "markdown": "<div align=\"center\">\n\n# 🪣 s3-mcp-connector\n\n**Talk to Amazon S3 — or LocalStack, MinIO, any S3-compatible store — from an MCP-speaking agent.**\n\n[![CI](https://github.com/FerhatDundar/s3-mcp-connector/actions/workflows/ci.yml/badge.svg)](https://github.com/FerhatDundar/s3-mcp-connector/actions/workflows/ci.yml)\n[![CodeQL](https://github.com/FerhatDundar/s3-mcp-connector/actions/workflows/codeql.yml/badge.svg)](https://github.com/FerhatDundar/s3-mcp-connector/actions/workflows/codeql.yml)\n[![Latest release](https://img.shields.io/github/v/release/FerhatDundar/s3-mcp-connector?color=blueviolet&label=release)](https://github.com/FerhatDundar/s3-mcp-connector/releases/latest)\n[![MCP Registry](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0%2Fservers%3Fsearch%3Ds3-mcp-connector&query=%24.servers%5B-1%3A%5D.server.version&label=MCP%20Registry&prefix=v&color=6A2FEE&logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=s3-mcp-connector)\n[![Go Reference](https://img.shields.io/badge/go-1.25%2B-00ADD8?logo=go&logoColor=white)](https://go.dev/)\n[![License: MIT](https://img.shields.io/badge/license-MIT-yellow.svg)](LICENSE)\n[![Tested with LocalStack](https://img.shields.io/badge/tested%20with-LocalStack-6A2FEE?logo=amazonaws&logoColor=white)](https://localstack.cloud/)\n[![MCP](https://img.shields.io/badge/protocol-MCP-orange)](https://modelcontextprotocol.io/)\n[![Conventional Commits](https://img.shields.io/badge/commits-conventional-ff69b4)](https://www.conventionalcommits.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n</div>\n\n---\n\nA single static Go binary that speaks the [Model Context Protocol](https://modelcontextprotocol.io/)\nand exposes 8 tools for working with S3: list buckets, list/read/write/delete\nobjects, create/delete buckets. Point it at real AWS or at a local\nLocalStack/MinIO instance with one environment variable — same binary,\nsame tools, zero code changes.\n\nNo Python, no `uv`, no runtime dependency to install — just a binary and\nan `.mcp.json`.\n\n## ✨ Why this exists\n\n> An agent that can only *talk about* your S3 buckets isn't that useful.\n> This gives it hands: it can look inside a bucket, read a config file out\n> of it, drop a report back in, or clean up a stale prefix — safely, with\n> guardrails on size and destructive actions built in.\n\n## 🧰 Tools\n\n| Tool | What it does | Write? |\n|---|---|:---:|\n| `s3_list_buckets` | List buckets visible to the credentials | |\n| `s3_list_objects` | List objects in a bucket, optional prefix, paginated | |\n| `s3_head_object` | Object metadata (size, type, ETag) without downloading | |\n| `s3_get_object` | Read an object's content — text or base64, size-capped | |\n| `s3_put_object` | Write a small text/base64 object (≤ 5 MB) | ✍️ |\n| `s3_delete_object` | Delete one object | 🗑️ destructive |\n| `s3_create_bucket` | Create a bucket | ✍️ |\n| `s3_delete_bucket` | Delete an *empty* bucket | 🗑️ destructive |\n\nEvery tool accepts an optional `response_format`: `markdown` (default,\npretty tables for a chat UI) or `json` (for programmatic use).\n\n`s3_get_object` auto-detects text vs. binary content and caps output at\n**200,000 bytes** by default (raise via `max_bytes`, hard cap\n**5,000,000**) — it's built for reading configs, logs, and small data\nfiles, not bulk transfer. Reach for the AWS CLI or SDK directly for large\nobjects.\n\n## 🚀 Quickstart\n\n**Fastest path:** grab a prebuilt bundle from the [latest release](https://github.com/FerhatDundar/s3-mcp-connector/releases/latest) —\ndownload `s3-mcp-connector-plugin-<version>-<os>-<arch>.zip`, unzip it,\nand point Cowork/Claude at the `plugin/` folder inside (see step 4 of\n[SETUP.md](SETUP.md)). No Go toolchain required.\n\n**From source:**\n\n```bash\n# 1. Build\ncd go-server\ngo mod tidy\ngo build -o s3-connector-server .\ncp s3-connector-server ../plugin/servers/go/\n\n# 2. Spin up LocalStack to test against (no AWS account needed)\ncd ..\ndocker compose up -d\n\n# 3. Point the connector at it\nexport AWS_ACCESS_KEY_ID=test\nexport AWS_SECRET_ACCESS_KEY=test\nexport AWS_REGION=us-east-1\nexport S3_ENDPOINT_URL=http://localhost:4566\nexport S3_FORCE_PATH_STYLE=true\n\n./go-server/s3-connector-server   # serves MCP over stdio\n```\n\nOr `make build && make localstack-up` — see the [Makefile](Makefile) for\nevery shortcut (`test`, `vet`, `fmt`, `lint`, `tidy`, `localstack-down`).\n\nFull walkthrough — including wiring this up as a Claude/Cowork plugin and\nswitching from LocalStack to real AWS — is in **[SETUP.md](SETUP.md)**.\n\n## 🔐 Configuration\n\nEverything is environment variables, passed through by the plugin's\n`.mcp.json`:\n\n| Variable | Purpose | Default |\n|---|---|---|\n| `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` | AWS credentials. Any non-empty values work against LocalStack. | — |\n| `AWS_REGION` | Region to use. | `us-east-1` |\n| `S3_ENDPOINT_URL` | Custom endpoint. Leave unset for real AWS. | *(unset)* |\n| `S3_FORCE_PATH_STYLE` | `true` for LocalStack/MinIO (path-style addressing). | `false` |\n\n## 🧪 Quality bar\n\nThis isn't a toy script — it's got the same checks you'd expect from a\nproduction Go service:\n\n- ✅ **Unit tests** for every input-validation path (`go test ./...`)\n- ✅ **`go vet`** + **`gofmt`** clean\n- ✅ **[golangci-lint](https://golangci-lint.run/)** (govet, staticcheck, errcheck, gosec, and more)\n- ✅ **[govulncheck](https://go.dev/blog/vuln)** — no known vulnerabilities in the dependency graph\n- ✅ **[CodeQL](https://codeql.github.com/)** static security analysis on every push\n- ✅ **End-to-end verified against real LocalStack** — every tool\n  (create/delete bucket, put/get/head/list/delete object, and the 404\n  error path) was exercised against a live S3-compatible service, not\n  mocks\n- ✅ **[Dependabot](.github/dependabot.yml)** keeps Go modules and Actions current\n\nAll of it runs in [CI](.github/workflows/ci.yml) on every push and PR.\n\n## 🏷️ Releases & versioning\n\nVersions follow [semver](https://semver.org/) and are cut automatically by\n[release-please](https://github.com/googleapis/release-please) from\n[Conventional Commits](https://www.conventionalcommits.org/) on `main`:\n\n- `fix: ...` → patch (`v0.1.0` → `v0.1.1`)\n- `feat: ...` → minor (`v0.1.1` → `v0.2.0`)\n- `feat!: ...` / `BREAKING CHANGE:` footer → major (`v0.2.0` → `v1.0.0`)\n\nEvery merged PR updates a standing **\"chore(main): release vX.Y.Z\"** PR\nwith an auto-generated [CHANGELOG.md](CHANGELOG.md). Merging that PR:\n\n1. tags the release and publishes it on GitHub\n2. builds and attaches zipped, ready-to-install plugin bundles for\n   linux/darwin/windows × amd64/arm64\n3. regenerates `server.json` from those exact assets (fresh version +\n   SHA-256 hashes) and publishes it to the\n   [official MCP Registry](https://registry.modelcontextprotocol.io/) via\n   `mcp-publisher`, authenticated with GitHub OIDC — no stored secrets\n\nSee [.github/workflows/release-please.yml](.github/workflows/release-please.yml)\nand [.github/workflows/publish-mcp-registry.yml](.github/workflows/publish-mcp-registry.yml)\n(also runnable by hand for an existing tag via `workflow_dispatch`).\n\n## 📁 Layout\n\n```\ns3-mcp-connector/\n├── README.md                  ← you are here\n├── SETUP.md                   ← step-by-step setup guide (LocalStack + real AWS)\n├── CONTRIBUTING.md             ← how to contribute\n├── CODE_OF_CONDUCT.md\n├── SECURITY.md                 ← vulnerability reporting\n├── CODEOWNERS\n├── LICENSE                     ← MIT\n├── Makefile                    ← build / test / lint / localstack shortcuts\n├── docker-compose.yml          ← LocalStack, for local testing\n├── .golangci.yml                ← lint rules\n├── release-please-config.json  ← semver/changelog automation config\n├── .release-please-manifest.json\n├── server.json                  ← MCP Registry manifest (regenerated fresh per release by CI)\n├── scripts/\n│   └── render-server-json.sh    ← rebuilds server.json from a release's zip assets\n├── .github/\n│   ├── workflows/\n│   │   ├── ci.yml                     ← build, vet, test, lint, govulncheck\n│   │   ├── codeql.yml                 ← security scanning\n│   │   ├── pr-title.yml               ← Conventional Commits PR title check\n│   │   ├── release-please.yml         ← version PRs, tagging, GitHub releases\n│   │   ├── publish-mcp-registry.yml   ← publishes server.json to the MCP Registry\n│   │   └── rebuild-release-assets.yml ← manual re-attach fallback\n│   ├── ISSUE_TEMPLATE/\n│   ├── PULL_REQUEST_TEMPLATE.md\n│   └── dependabot.yml\n├── go-server/                  ← the MCP server source\n│   ├── main.go\n│   ├── main_test.go\n│   ├── go.mod / go.sum\n│   └── README.md\n└── plugin/                     ← installable Cowork/Claude plugin\n    ├── .claude-plugin/plugin.json\n    ├── .mcp.json                ← holds credentials locally — never commit real ones\n    └── servers/go/              ← compiled binary goes here\n```\n\n## 🤝 Contributing\n\nPRs and issues are very welcome — see **[CONTRIBUTING.md](CONTRIBUTING.md)**\nfor the full guide (setup, coding conventions, how to add a new tool) and\nthe **[Code of Conduct](CODE_OF_CONDUCT.md)**.\n\n`main` is protected: every change, including the maintainer's, lands via\npull request with CI green. PR titles must follow\n[Conventional Commits](https://www.conventionalcommits.org/) — that's what\ndrives the automatic versioning above.\n\nFound a security issue? Please follow **[SECURITY.md](SECURITY.md)**\ninstead of opening a public issue.\n\n## 📄 License\n\n[MIT](LICENSE) © Ferhat Dundar\n",
  "bytes": 9526,
  "sha": "9534b3c08f9d9672b06ede3b356e8d30a8cde5fc19ba86c20e42c4d54a064d56",
  "repo_slug": "ferhatdundar/s3-mcp-connector",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ferhatdundar_s3_mcp_connector_4b9280f2/readme"
}