s3-mcp-connector

---

Model Context Protocol に対応した、単一の静的 Go バイナリです。S3 での操作に使える 8 つのツール（バケットの一覧表示、オブジェクトの一覧表示／読み取り／書き込み／削除、バケットの作成／削除）を提供します。環境変数を 1 つ設定するだけで、実際の AWS またはローカルの LocalStack／MinIO インスタンスに接続できます。バイナリもツールも同じままで、コードの変更は不要です。

Python も uv も、インストールが必要なランタイム依存関係もありません。必要なのはバイナリと .mcp.json だけです。

✨ これが作られた理由

S3 バケットについて話すだけのエージェントは、あまり役に立ちません。 このツールを使えば、エージェントは実際に操作できます。バケットの中を確認したり、設定ファイルを読み取ったり、レポートを書き込んだり、古くなったプレフィックスを安全に削除したりできます。サイズ制限と破壊的な操作に対するガードレールも組み込まれています。

🧰 ツール

ツール	内容	書き込み？
s3_list_buckets	認証情報から参照できるバケットを一覧表示します
s3_list_objects	バケット内のオブジェクトを一覧表示します。プレフィックス指定とページネーションに対応しています
s3_head_object	ダウンロードせずにオブジェクトのメタデータ（サイズ、タイプ、ETag）を取得します
s3_get_object	オブジェクトの内容を読み取ります。テキストまたは base64 に対応し、サイズを制限します
s3_put_object	小さなテキスト／base64 オブジェクト（≤ 5 MB）を書き込みます	✍️
s3_delete_object	オブジェクトを 1 つ削除します	🗑️ 破壊的
s3_create_bucket	バケットを作成します	✍️
s3_delete_bucket	空のバケットを削除します	🗑️ 破壊的

すべてのツールでは、任意の response_format を指定できます。markdown（デフォルト。チャット UI 向けの見やすい表）または json（プログラムからの利用向け）を選べます。

s3_get_object はテキストとバイナリの内容を自動判定し、出力をデフォルトで 200,000 bytes までに制限します（max_bytes で引き上げ可能。ハード上限は 5,000,000 です）。設定ファイル、ログ、小さなデータファイルの読み取り向けであり、大量データの転送には適していません。大きなオブジェクトには AWS CLI または SDK を直接お使いください。

🚀 クイックスタート

最速の方法： 最新リリースからビルド済みバンドルを取得します — s3-mcp-connector-plugin-<version>-<os>-<arch>.zip をダウンロードして展開し、 中にある plugin/ フォルダーを Cowork/Claude に指定します（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 を実行します — あらゆるショートカット（test、vet、fmt、lint、tidy、localstack-down）については Makefile を参照してください。

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 に対するエンドツーエンド検証済み — すべてのツール （バケットの作成／削除、オブジェクトの put/get/head/list/delete、および 404 エラー経路）をモックではなく、稼働中の S3 互換サービスに対して実行しました
• ✅ Dependabot が Go モジュールと Actions を最新の状態に保ちます

これらはすべて、プッシュと PR のたびに CI で実行されます。

🏷️ リリースとバージョニング

バージョンは semver に従い、main に対する Conventional Commits から release-please によって自動的に作成されます。

• fix: ... → パッチ（v0.1.0 → v0.1.1）
• feat: ... → マイナー（v0.1.1 → v0.2.0）
• feat!: ... / BREAKING CHANGE: フッター → メジャー（v0.2.0 → v1.0.0）

マージされた PR ごとに、自動生成された CHANGELOG.md を含む継続的な "chore(main): release vX.Y.Z" PR が更新されます。この PR をマージすると、次の処理が行われます。

1. リリースにタグを付け、GitHub で公開します
2. linux/darwin/windows × amd64/arm64 向けに、インストール可能なプラグインバンドルを ZIP 形式でビルドし、添付します
3. その正確なアセットから server.json を再生成し（最新バージョンと SHA-256 ハッシュを反映）、GitHub OIDC で認証した mcp-publisher を通じて 公式 MCP Registry に公開します — シークレットの保存は不要です

.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 や Issue を歓迎します — 詳しいガイド（セットアップ、コーディング規約、新しいツールの追加方法）と 行動規範 については、CONTRIBUTING.md を参照してください。

main は保護されています。メンテナーによる変更を含め、すべての変更は CI が成功した状態でプルリクエストを通じて反映されます。PR のタイトルは Conventional Commits に従う必要があります — これは上記の自動バージョニングに使用されます。

セキュリティ上の問題を見つけた場合は、公開 Issue を作成せず、SECURITY.md の手順に従ってください。

📄 ライセンス

MIT © Ferhat Dundar