s3-mcp-connector

---

这是一个静态 Go 二进制程序，支持 Model Context Protocol， 并提供 8 个用于操作 S3 的工具：列出存储桶、列出/读取/写入/删除对象，以及创建/删除存储桶。只需设置一个环境变量，即可将其连接到真实的 AWS 或本地 LocalStack/MinIO 实例——使用同一个二进制程序和相同的工具，无需更改代码。

无需 Python、无需 uv，也无需安装运行时依赖——只需一个二进制程序和一个 .mcp.json。

✨ 为什么要做这个项目

只能 谈论 你的 S3 存储桶的 Agent 用处不大。 这个工具让它能够动手操作：查看存储桶内容、读取其中的配置文件、写入报告，或清理过期前缀——所有操作都安全可控，并内置大小限制和破坏性操作防护。

🧰 工具

工具	功能	写入？
s3_list_buckets	列出凭据可访问的存储桶
s3_list_objects	列出存储桶中的对象，可选前缀，支持分页
s3_head_object	查看对象元数据（大小、类型、ETag），无需下载
s3_get_object	读取对象内容——文本或 base64，并限制大小
s3_put_object	写入较小的文本/base64 对象（≤ 5 MB）	✍️
s3_delete_object	删除单个对象	🗑️ 破坏性操作
s3_create_bucket	创建存储桶	✍️
s3_delete_bucket	删除空存储桶	🗑️ 破坏性操作

每个工具都接受可选参数 response_format：markdown（默认值，为聊天界面生成美观表格）或 json（用于程序化处理）。

s3_get_object 会自动识别文本和二进制内容，默认将输出限制为 200,000 字节（可通过 max_bytes 提高，硬性上限为 5,000,000 字节）——适合读取配置、日志和小型数据 文件，不适合批量传输。对于大型对象，请直接使用 AWS CLI 或 SDK。

🚀 快速开始

**最快方式：**从最新版本获取预构建包 — 下载 s3-mcp-connector-plugin-<version>-<os>-<arch>.zip，解压后， 将 Cowork/Claude 指向其中的 plugin/ 文件夹（参见 SETUP.md 的第 4 步）。无需 Go 工具链。

从源代码构建：

# 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

或者运行 make build && make localstack-up — 请参阅 Makefile，了解 所有快捷命令（test、vet、fmt、lint、tidy、localstack-down）。

完整操作指南 — 包括如何将其配置为 Claude/Cowork 插件，以及 如何从 LocalStack 切换到真实 AWS — 请参阅 SETUP.md。

🔐 配置

所有配置均通过环境变量设置，并由插件的 .mcp.json 传递：

变量	用途	默认值
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	AWS 凭证。连接 LocalStack 时，任意非空值均可使用。	—
AWS_REGION	使用的区域。	us-east-1
S3_ENDPOINT_URL	自定义端点。连接真实 AWS 时请留空。	（未设置）
S3_FORCE_PATH_STYLE	在 LocalStack/MinIO 中使用 true（路径风格寻址）。	false

🧪 质量标准

这不是一个玩具脚本 — 它具备生产级 Go 服务应有的检查：

• ✅ 对每条输入验证路径进行单元测试（go test ./...）
• ✅ go vet + gofmt 检查通过
• ✅ golangci-lint（govet、staticcheck、errcheck、gosec 等）
• ✅ govulncheck — 依赖关系图中没有已知漏洞
• ✅ 每次推送都会运行 CodeQL 静态安全分析
• ✅ 通过真实 LocalStack 端到端验证 — 每个工具 （创建/删除存储桶、上传/获取/查看/列出/删除对象，以及 404 错误路径）都在运行中的 S3 兼容服务上进行了测试，而非 使用模拟对象
• ✅ Dependabot 会及时更新 Go 模块和 Actions

所有检查都会在每次推送和 PR 时通过 CI 运行。

🏷️ 发布与版本管理

版本遵循 semver 规范，并由 release-please 根据 main 分支上的 Conventional Commits 自动发布：

• fix: ... → 修订版（v0.1.0 → v0.1.1）
• feat: ... → 次版本（v0.1.1 → v0.2.0）
• feat!: ... / BREAKING CHANGE: 页脚 → 主版本（v0.2.0 → v1.0.0）

每个合并的 PR 都会更新一个长期存在的 "chore(main): release vX.Y.Z" PR， 并自动生成 CHANGELOG.md。合并该 PR 后：

1. 为版本打标签并在 GitHub 上发布
2. 构建并附加可直接安装的压缩插件包，支持 linux/darwin/windows × amd64/arm64
3. 根据这些确切的资源重新生成 server.json（更新版本号 + SHA-256 哈希），并通过 mcp-publisher 发布到 官方 MCP Registry，使用 GitHub OIDC 进行身份验证 — 无需存储密钥

请参阅 .github/workflows/release-please.yml 和 .github/workflows/publish-mcp-registry.yml （也可通过 workflow_dispatch 手动对已有标签运行）。

📁 目录结构

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

🤝 贡献

欢迎提交 PR 和问题 — 完整指南（包括环境设置、编码规范以及如何添加新工具）请参阅 CONTRIBUTING.md， 以及**行为准则**。

main 分支受保护：所有更改（包括维护者提交的更改）都必须通过 CI 检查通过的 pull request 合并。PR 标题必须遵循 Conventional Commits — 这是上述自动版本管理的依据。

发现安全问题？请遵循 SECURITY.md 中的说明， 不要公开提交问题。

📄 许可证

MIT © Ferhat Dundar