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.

Related MCP server: AWS MCP Server

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

1. Ü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

2. 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

3. 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:

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

1. Erstellen Sie das Docker-Image:

docker build -t aws-s3-mcp .

2. 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

3. Überprüfen Sie die Containerprotokolle:

docker logs aws-s3-mcp-server

4. 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

1. 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

2. 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:

1. Starten Sie MinIO und die S3 MCP-Servercontainer, falls diese nicht ausgeführt werden

2. Starten Sie den mit dem S3 MCP-Server verbundenen MCP Inspector

3. 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:

1. Bearbeiten Sie Ihre Claude Desktop-Konfigurationsdatei:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 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