S3 MCP-Server

Ein Amazon S3 Model Context Protocol (MCP)-Server, der Tools für die Interaktion mit S3-Buckets und -Objekten bereitstellt.

https://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666

Überblick

Dieser MCP-Server ermöglicht Large Language Models (LLMs) wie Claude die Interaktion mit AWS S3-Speicher. Er bietet Tools für:

Auflisten verfügbarer S3-Buckets
Auflisten von Objekten innerhalb eines Buckets
Abrufen von Objektinhalten

Der Server wird mit TypeScript und dem MCP SDK erstellt und bietet LLMs eine sichere und standardisierte Möglichkeit, mit S3 zu interagieren.

Installation

Voraussetzungen

Node.js 18 oder höher
npm oder yarn
AWS-Anmeldeinformationen konfiguriert (entweder über Umgebungsvariablen oder AWS-Anmeldeinformationsdatei)
Docker (optional, für containerisiertes Setup)

Aufstellen

Über npm installieren:

# Install globally via npm
npm install -g aws-s3-mcp

# Or as a dependency in your project
npm install aws-s3-mcp

Beim Erstellen aus der Quelle:

# Clone the repository
git clone https://github.com/samuraikun/aws-s3-mcp.git
cd aws-s3-mcp

# Install dependencies and build
npm install
npm run build

Konfigurieren Sie AWS-Anmeldeinformationen und S3-Zugriff:

Erstellen Sie eine .env Datei mit Ihrer AWS-Konfiguration:

AWS_REGION=us-east-1
S3_BUCKETS=bucket1,bucket2,bucket3
S3_MAX_BUCKETS=5
AWS_ACCESS_KEY_ID=your-access-key
AWS_SECRET_ACCESS_KEY=your-secret-key

Oder legen Sie diese als Umgebungsvariablen fest.

Konfiguration

Der Server kann mit den folgenden Umgebungsvariablen konfiguriert werden:

Variable	Beschreibung	Standard
`AWS_REGION`	AWS-Region, in der sich Ihre S3-Buckets befinden	`us-east-1`
`S3_BUCKETS`	Durch Kommas getrennte Liste zulässiger S3-Bucket-Namen	(leer)
`S3_MAX_BUCKETS`	Maximale Anzahl von Buckets, die in der Auflistung zurückgegeben werden sollen	`5`
`AWS_ACCESS_KEY_ID`	AWS-Zugriffsschlüssel (wenn keine Standardanmeldeinformationen verwendet werden)	(aus der AWS-Konfiguration)
`AWS_SECRET_ACCESS_KEY`	AWS-Geheimschlüssel (wenn keine Standardanmeldeinformationen verwendet werden)	(aus der AWS-Konfiguration)

Ausführen des Servers

Direkte Node.js-Ausführung

Sie können den Server direkt mit Node.js ausführen:

# Using npx (without installing)
npx aws-s3-mcp

# If installed globally
npm install -g aws-s3-mcp
aws-s3-mcp

# If running from cloned repository
npm start

# Or directly
node dist/index.js

Docker-Setup 🐳

Sie können den S3 MCP-Server als Docker-Container ausführen, indem Sie entweder Docker CLI oder Docker Compose verwenden.

Verwenden der Docker-CLI

Erstellen Sie das Docker-Image:

docker build -t aws-s3-mcp .

Führen Sie den Container mit Umgebungsvariablen aus:

# Option 1: Pass environment variables directly
docker run -d \
  -e AWS_REGION=us-east-1 \
  -e S3_BUCKETS=bucket1,bucket2 \
  -e S3_MAX_BUCKETS=5 \
  -e AWS_ACCESS_KEY_ID=your-access-key \
  -e AWS_SECRET_ACCESS_KEY=your-secret-key \
  --name aws-s3-mcp-server \
  aws-s3-mcp

# Option 2: Use environment variables from .env file
docker run -d \
  --env-file .env \
  --name aws-s3-mcp-server \
  aws-s3-mcp

Überprüfen Sie die Containerprotokolle:

docker logs aws-s3-mcp-server

Anhalten und Behälter entfernen:

docker stop aws-s3-mcp-server
docker rm aws-s3-mcp-server

Beachten Sie, dass der Container keine Ports verfügbar macht, da er für die Verwendung mit Claude Desktop über Docker Exec und nicht über direkte HTTP-Verbindungen konzipiert ist.

Verwenden von Docker Compose

Erstellen und starten Sie den Docker-Container:

# Build and start the container
docker compose up -d s3-mcp

# View logs
docker compose logs -f s3-mcp

So stoppen Sie den Container:

docker compose down

Docker mit MinIO zum Testen verwenden

Das Docker Compose-Setup umfasst einen MinIO-Dienst für lokale Tests:

# Start MinIO and the MCP server
docker compose up -d

# Access MinIO console at http://localhost:9001
# Default credentials: minioadmin/minioadmin

Der MinIO-Dienst erstellt automatisch zwei Test-Buckets ( test-bucket-1 und test-bucket-2 ) und lädt Beispieldateien zum Testen hoch.

Debuggen mit MCP Inspector

So debuggen Sie den Server mit MCP Inspector:

# Run inspector with local Node.js
sh run-inspector.sh

# Run inspector with Docker Compose and MinIO
sh run-inspector.sh --docker-compose

# Run inspector with Docker CLI (without Docker Compose)
sh run-inspector.sh --docker

Bei Verwendung der Option --docker-compose führt das Skript Folgendes aus:

Starten Sie MinIO und die S3 MCP-Servercontainer, falls diese nicht ausgeführt werden
Starten Sie den mit dem S3 MCP-Server verbundenen MCP Inspector
Anschließend können Sie die S3-Tools mit der lokalen MinIO-Instanz testen

Verbindung zu Claude Desktop herstellen

So verwenden Sie diesen Server mit Claude Desktop:

Bearbeiten Sie Ihre Claude Desktop-Konfigurationsdatei:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Fügen Sie den S3 MCP-Server zur Konfiguration hinzu:

{
  "mcpServers": {
    "s3": {
      "command": "npx",
      "args": ["aws-s3-mcp"],
      "env": {
        "AWS_REGION": "us-east-1",
        "S3_BUCKETS": "bucket1,bucket2,bucket3",
        "S3_MAX_BUCKETS": "5",
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

Docker-Option für Claude Desktop 🐳

Sie können Claude Desktop auch so konfigurieren, dass ein laufender Docker-Container für den MCP-Server verwendet wird:

{
  "mcpServers": {
    "s3": {
      "command": "docker",
      "args": ["exec", "-i", "aws-s3-mcp-server", "node", "dist/index.js"],
      "env": {}
    }
  }
}

⚠️ Wichtige Voraussetzungen : Damit diese Docker-Konfiguration funktioniert, MÜSSEN Sie zuerst den Docker-Container erstellen und ausführen, BEVOR Sie Claude Desktop starten:
# 1. First, build the Docker image (only needed once or after changes) docker build -t aws-s3-mcp . # 2. Then start the container (required each time before using with Claude) # Using Docker Compose (recommended) docker compose up -d s3-mcp # Or using Docker CLI docker run -d --name aws-s3-mcp-server --env-file .env aws-s3-mcp
Ohne einen laufenden Container zeigt Claude Desktop beim Versuch, S3-Tools zu verwenden, Fehler an.
Die obige Docker-Konfiguration verwendet exec , um MCP-Anfragen direkt an den laufenden Container zu senden. Es ist keine Portzuordnung erforderlich, da Claude direkt mit dem Container kommuniziert und nicht über einen Netzwerkport.

Hinweis : Stellen Sie sicher, dass der Containername in der Konfiguration ( aws-s3-mcp-server ) mit dem Namen Ihres laufenden Containers übereinstimmt.

Wichtig : Bitte beachten Sie Folgendes, wenn Sie die obige Konfiguration verwenden
Ersetzen Sie AWS_ACCESS_KEY_ID und AWS_SECRET_ACCESS_KEY durch Ihre tatsächlichen Anmeldeinformationen
S3_BUCKETS sollte eine durch Kommas getrennte Liste der Buckets enthalten, auf die Sie Zugriff gewähren möchten
AWS_REGION sollte auf die Region eingestellt werden, in der sich Ihre Buckets befinden

💣 Wenn ein Fehler auf Claude Desktop auftritt

Wenn bei der obigen Konfiguration in Claude Desktop Fehler auftreten, versuchen Sie es mit absoluten Pfaden wie folgt:

# Get the path of node and aws-s3-mcp
which node
which aws-s3-mcp

{
  "globalShortcut": "",
  "mcpServers": {
    "s3": {
      "command": "your-absolute-path-to-node",
      "args": ["your-absolute-path-to-aws-s3-mcp/dist/index.js"],
      "env": {
        "AWS_REGION": "your-aws-region",
        "S3_BUCKETS": "your-s3-buckets",
        "S3_MAX_BUCKETS": "your-max-buckets",
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key"
      }
    }
  }
}

Verfügbare Tools

Bucket-Liste

Listet verfügbare S3-Buckets auf, auf die der Server Zugriff hat. Dieses Tool berücksichtigt die S3_BUCKETS -Konfiguration, die die angezeigten Buckets einschränkt.

Parameter: Keine

Beispielausgabe:

[
  {
    "Name": "my-images-bucket",
    "CreationDate": "2022-03-15T10:30:00.000Z"
  },
  {
    "Name": "my-documents-bucket",
    "CreationDate": "2023-05-20T14:45:00.000Z"
  }
]

Listenobjekte

Listet Objekte in einem angegebenen S3-Bucket auf.

Parameter:

bucket (erforderlich): Name des S3-Buckets, aus dem Objekte aufgelistet werden sollen
prefix (optional): Präfix zum Filtern von Objekten (wie ein Ordnerpfad)
maxKeys (optional): Maximale Anzahl der zurückzugebenden Objekte

Beispielausgabe:

[
  {
    "Key": "sample.pdf",
    "LastModified": "2023-10-10T08:12:15.000Z",
    "Size": 2048576,
    "StorageClass": "STANDARD"
  },
  {
    "Key": "sample.md",
    "LastModified": "2023-10-12T15:30:45.000Z",
    "Size": 1536000,
    "StorageClass": "STANDARD"
  }
]

Objekt abrufen

Ruft ein Objekt aus einem angegebenen S3-Bucket ab. Textdateien werden als einfacher Text zurückgegeben, Binärdateien mit eingeschränkten Details.

Parameter:

bucket (erforderlich): Name des S3-Buckets
key (erforderlich): Schlüssel (Pfad) des abzurufenden Objekts

Beispiel für eine Textausgabe:

This is the content of a text file stored in S3.
It could be JSON, TXT, CSV or other text-based formats.

Beispiel einer Binärausgabe:

Binary content (image/jpeg): base64 data is /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof...

Sicherheitsüberlegungen

Der Server greift nur auf die Buckets zu, die in der Umgebungsvariable S3_BUCKETS angegeben sind.
AWS-Anmeldeinformationen müssen über die entsprechenden Berechtigungen für die Buckets verfügen
Verwenden Sie beim Konfigurieren von AWS-Berechtigungen das Prinzip der geringsten Privilegien
Für den Produktionseinsatz sollten Sie die Verwendung von IAM-Rollen mit spezifischen S3-Berechtigungen in Betracht ziehen

Verwendung mit Claude

Wenn Sie mit Claude in der Desktop-App interagieren, können Sie ihn bitten, S3-Operationen auszuführen wie:

„Liste alle meine S3-Buckets auf“
"PDF-Dateien im My-Documents-Bucket zusammenfassen"
„Holen Sie sich die Datei README.txt aus meinem Dokumenten-Bucket.“

Claude verwendet das entsprechende MCP-Tool, um die Anfrage auszuführen und Ihnen die Ergebnisse anzuzeigen.

Lizenz

MIT

S3 MCP Server

Integrations