AWS S3 MCP Server

Servidor MCP de AWS S3

Un servidor de Protocolo de Contexto de Modelo (MCP) que brinda a los asistentes de IA (Claude, Cursor, etc.) acceso directo a AWS S3, permitiéndoles listar, subir, descargar y gestionar buckets y objetos de S3 mediante lenguaje natural.

---

Por Qué Existe

Al construir pipelines de agentes de IA, a menudo necesitas que los agentes lean o escriban en S3 — ya sea para obtener documentos para RAG, persistir resultados o gestionar archivos dinámicamente. Este servidor MCP cierra esa brecha al exponer operaciones de S3 como herramientas MCP, de modo que cualquier cliente de IA compatible con MCP pueda interactuar con S3 sin necesidad de integración personalizada.

---

Requisitos Previos

• Node.js 18+
• Cuenta de AWS con acceso a S3
• Credenciales de AWS (ID de clave de acceso + secreto, o rol de IAM)
• Un cliente compatible con MCP (Claude Desktop, Cursor, etc.)

---

Inicio Rápido

1. Instalar vía npx (sin necesidad de instalación)

{
  "mcpServers": {
    "aws-s3": {
      "command": "npx",
      "args": ["@gangadharrr/aws-s3"],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_ACCESS_KEY_ID": "your-access-key-id",
        "AWS_SECRET_ACCESS_KEY": "your-secret-access-key"
      },
      "autoApprove": ["list_buckets", "list_objects", "get_bucket_policy"]
    }
  }
}

Agrega esto al archivo de configuración de tu cliente MCP:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: .cursor/mcp.json en la raíz de tu proyecto

2. Usando credenciales de la CLI de AWS (recomendado para desarrollo local)

Si ya configuraste la CLI de AWS (aws configure), puedes omitir las variables de entorno de clave:

{
  "mcpServers": {
    "aws-s3": {
      "command": "npx",
      "args": ["@gangadharrr/aws-s3"],
      "env": {
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

---

Herramientas Disponibles

Herramienta	Descripción
list_buckets	Lista todos los buckets de S3 en la cuenta
create_bucket	Crea un nuevo bucket de S3
delete_bucket	Elimina un bucket de S3 vacío
list_objects	Lista objetos en un bucket (con filtro de prefijo opcional)
upload_object	Sube un archivo o contenido de texto a un bucket
download_object	Descarga un objeto de un bucket
delete_object	Elimina un objeto de un bucket
get_bucket_policy	Obtiene la política adjunta a un bucket
set_bucket_policy	Establece o actualiza una política de bucket

---

Referencia de Herramientas

list_buckets

Lista todos los buckets de S3 en la cuenta de AWS.

Parámetros: Ninguno

Respuesta:

{
  "success": true,
  "buckets": [
    { "name": "my-bucket", "creationDate": "2023-01-15T00:00:00.000Z" }
  ],
  "count": 1
}

---

create_bucket

Crea un nuevo bucket de S3.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
bucketName	string	✅	Nombre del bucket a crear
region	string	❌	Región de AWS (por defecto usa la región configurada)

Respuesta:

{
  "success": true,
  "bucketName": "my-new-bucket",
  "location": "http://my-new-bucket.s3.amazonaws.com/"
}

---

list_objects

Lista objetos en un bucket con filtrado de prefijo opcional.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
bucketName	string	✅	Bucket del cual listar objetos
prefix	string	❌	Filtrar por prefijo (ruta de carpeta)
maxKeys	number	❌	Máximo de resultados (por defecto: 1000)
continuationToken	string	❌	Token de paginación

---

upload_object

Sube un archivo o contenido de texto a S3.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
bucketName	string	✅	Bucket de destino
key	string	✅	Clave del objeto (ruta) en el bucket
filePath	string	❌	Ruta del archivo local a subir
content	string	❌	Contenido de texto para subir directamente
contentType	string	❌	Tipo MIME del contenido

---

download_object

Descarga un objeto de S3.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
bucketName	string	✅	Bucket de origen
key	string	✅	Clave del objeto (ruta) a descargar
outputPath	string	❌	Ruta local para guardar el archivo
returnContent	boolean	❌	Devolver el contenido en línea en la respuesta

---

delete_object

Elimina un objeto de un bucket.

Parámetros:

Nombre	Tipo	Obligatorio	Descripción
bucketName	string	✅	Bucket que contiene el objeto
key	string	✅	Clave del objeto a eliminar

---

get_bucket_policy / set_bucket_policy

Obtiene o establece la política de IAM para un bucket.

Parámetros para set_bucket_policy:

Nombre	Tipo	Obligatorio	Descripción
bucketName	string	✅	Bucket de destino
policy	string/object	✅	Documento de política (cadena JSON u objeto)

---

Autenticación de AWS

El servidor utiliza la cadena de resolución de credenciales del SDK de AWS en este orden:

1. Variables de entorno — AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
2. Archivo de credenciales compartidas — ~/.aws/credentials (configurado mediante aws configure)
3. Metadatos de instancia EC2 — si se ejecuta en una instancia EC2 con un rol de IAM

Para producción, se recomiendan roles de IAM en lugar de credenciales estáticas.

---

Contribuciones

¡Las contribuciones son bienvenidas! Si deseas agregar una nueva operación de S3 o mejorar las existentes:

1. Haz un fork del repositorio
2. Crea una rama de funcionalidad: git checkout -b feature/my-new-tool
3. Realiza tus cambios: git commit -m 'Add: new S3 tool'
4. Haz push y abre una Solicitud de Extracción (Pull Request)

---

Licencia

MIT — consulta LICENSE para más detalles.

---

Construido con el SDK de TypeScript de MCP y el SDK de AWS v3.