Servidor S3 MCP

Un servidor de Protocolo de contexto de modelo (MCP) de Amazon S3 que proporciona herramientas para interactuar con objetos y depósitos de S3.

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

Descripción general

Este servidor MCP permite que los modelos de lenguaje grandes (LLM) como Claude interactúen con el almacenamiento de AWS S3. Proporciona herramientas para:

• Listado de buckets S3 disponibles

• Listado de objetos dentro de un depósito

• Recuperando el contenido de un objeto

El servidor está construido utilizando TypeScript y MCP SDK, lo que proporciona una forma segura y estandarizada para que los LLM interactúen con S3.

Related MCP server: AWS MCP Server

Instalación

Prerrequisitos

• Node.js 18 o superior

• npm o hilo

• Credenciales de AWS configuradas (ya sea a través de variables de entorno o archivo de credenciales de AWS)

• Docker (opcional, para configuración en contenedores)

Configuración

1. Instalar mediante npm:

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

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

2. Si se construye desde la fuente:

# 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. Configurar las credenciales de AWS y el acceso a S3:

Cree un archivo .env con su configuración de AWS:

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

O configúrelos como variables de entorno.

Configuración

El servidor se puede configurar utilizando las siguientes variables de entorno:

Ejecución del servidor

Ejecución directa de Node.js

Puedes ejecutar el servidor directamente con Node.js:

# 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

Configuración de Docker 🐳

Puede ejecutar el servidor S3 MCP como un contenedor Docker utilizando Docker CLI o Docker Compose.

Uso de Docker CLI

1. Construya la imagen de Docker:

docker build -t aws-s3-mcp .

2. Ejecute el contenedor con variables de entorno:

# 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. Comprobar los registros del contenedor:

docker logs aws-s3-mcp-server

4. Detener y retirar el contenedor:

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

Tenga en cuenta que el contenedor no expone ningún puerto porque está diseñado para usarse con Claude Desktop a través de Docker exec en lugar de conexiones HTTP directas.

Uso de Docker Compose

1. Construya e inicie el contenedor Docker:

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

# View logs
docker compose logs -f s3-mcp

2. Para detener el contenedor:

docker compose down

Uso de Docker con MinIO para pruebas

La configuración de Docker Compose incluye un servicio MinIO para pruebas locales:

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

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

El servicio MinIO crea automáticamente dos grupos de pruebas ( test-bucket-1 y test-bucket-2 ) y carga archivos de muestra para realizar pruebas.

Depuración en MCP Inspector

Para depurar el servidor usando 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

Al utilizar la opción --docker-compose , el script hará lo siguiente:

1. Inicie MinIO y los contenedores del servidor S3 MCP si no se están ejecutando

2. Inicie el Inspector MCP conectado al servidor MCP de S3

3. Luego puede probar las herramientas S3 contra la instancia local de MinIO.

Conexión a Claude Desktop

Para utilizar este servidor con Claude Desktop:

1. Edite su archivo de configuración de Claude Desktop:

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

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

2. Agregue el servidor S3 MCP a la configuración:

{
  "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"
      }
    }
  }
}

Opción de Docker para Claude Desktop 🐳

También puede configurar Claude Desktop para utilizar un contenedor Docker en ejecución para el servidor MCP:

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

⚠️ Requisitos previos importantes : para que esta configuración de Docker funcione, primero DEBE compilar y ejecutar el contenedor Docker ANTES de iniciar Claude Desktop:

# 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

Sin un contenedor en ejecución, Claude Desktop mostrará errores al intentar utilizar herramientas S3.

La configuración de Docker anterior usa exec para enviar solicitudes MCP directamente al contenedor en ejecución. No se requiere la asignación de puertos, ya que Claude se comunica directamente con el contenedor en lugar de a través de un puerto de red.

Nota : asegúrese de que el nombre del contenedor en la configuración ( aws-s3-mcp-server ) coincida con el nombre del contenedor en ejecución.

Importante : tenga en cuenta lo siguiente al utilizar la configuración anterior

• Reemplace AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY con sus credenciales reales

• S3_BUCKETS debe contener una lista separada por comas de los depósitos a los que desea permitir el acceso.

• AWS_REGION debe configurarse en la región donde se encuentran sus buckets

💣 Si ocurre un error en Claude Desktop

Si encuentra errores con la configuración anterior en Claude Desktop, intente utilizar rutas absolutas de la siguiente manera:

# 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"
      }
    }
  }
}

Herramientas disponibles

lista de cubos

Enumera los buckets de S3 disponibles a los que el servidor tiene permiso de acceso. Esta herramienta respeta la configuración S3_BUCKETS , que limita los buckets que se muestran.

Parámetros: Ninguno

Ejemplo de salida:

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

lista de objetos

Enumera los objetos en un bucket S3 específico.

Parámetros:

• bucket (obligatorio): nombre del bucket S3 del que se listarán los objetos

• prefix (opcional): prefijo para filtrar objetos (como una ruta de carpeta)

• maxKeys (opcional): Número máximo de objetos a devolver

Ejemplo de salida:

[
  {
    "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"
  }
]

obtener objeto

Recupera un objeto de un bucket de S3 especificado. Los archivos de texto se devuelven como texto sin formato, mientras que los archivos binarios se devuelven con detalles limitados.

Parámetros:

• bucket (obligatorio): nombre del bucket S3

• key (obligatoria): Clave (ruta) del objeto a recuperar

Ejemplo de salida de texto:

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

Ejemplo de salida binaria:

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

Consideraciones de seguridad

• El servidor solo accederá a los depósitos especificados en la variable de entorno S3_BUCKETS

• Las credenciales de AWS deben tener los permisos adecuados para los depósitos

• Utilice el principio del mínimo privilegio al configurar los permisos de AWS

• Para uso en producción, considere usar roles de IAM con permisos S3 específicos

Uso con Claude

Al interactuar con Claude en la aplicación de escritorio, puedes pedirle que realice operaciones S3 como:

• "Enumerar todos mis buckets S3"

• Resumir archivos PDF en la carpeta "Mis documentos"

• Obtener el archivo README.txt de my-documents-bucket

Claude utilizará la herramienta MCP adecuada para realizar la solicitud y mostrarle los resultados.

Licencia

Instituto Tecnológico de Massachusetts (MIT)