AWS S3 MCP Server

Servidor MCP AWS S3

Um servidor Model Context Protocol (MCP) que dá aos assistentes de IA (Claude, Cursor, etc.) acesso direto ao AWS S3 — permitindo que eles listem, enviem, baixem e gerenciem buckets e objetos S3 por meio de linguagem natural.

---

Por Que Isso Existe

Ao criar pipelines de agentes de IA, você frequentemente precisa que os agentes leiam ou gravem no S3 — seja para buscar documentos para RAG, persistir saídas ou gerenciar arquivos dinamicamente. Este servidor MCP preenche essa lacuna expondo operações S3 como ferramentas MCP, para que qualquer cliente de IA compatível com MCP possa interagir com o S3 sem trabalho de integração personalizado.

---

Pré-requisitos

• Node.js 18+
• Conta AWS com acesso ao S3
• Credenciais AWS (Access Key ID + Secret, ou função IAM)
• Um cliente compatível com MCP (Claude Desktop, Cursor, etc.)

---

Início Rápido

1. Instale via npx (sem necessidade de instalação)

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

Adicione isto ao arquivo de configuração do seu cliente MCP:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: .cursor/mcp.json na raiz do seu projeto

2. Usando credenciais da AWS CLI (recomendado para desenvolvimento local)

Se você já configurou a AWS CLI (aws configure), pode omitir as variáveis de ambiente de chave:

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

---

Ferramentas Disponíveis

Ferramenta	Descrição
list_buckets	Lista todos os buckets S3 na conta
create_bucket	Cria um novo bucket S3
delete_bucket	Exclui um bucket S3 vazio
list_objects	Lista objetos em um bucket (com filtro de prefixo opcional)
upload_object	Envia um arquivo ou conteúdo de string para um bucket
download_object	Baixa um objeto de um bucket
delete_object	Exclui um objeto de um bucket
get_bucket_policy	Obtém a política anexada a um bucket
set_bucket_policy	Define ou atualiza uma política de bucket

---

Referência de Ferramentas

list_buckets

Lista todos os buckets S3 na conta AWS.

Parâmetros: Nenhum

Resposta:

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

---

create_bucket

Cria um novo bucket S3.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
bucketName	string	✅	Nome do bucket a ser criado
region	string	❌	Região AWS (padrão: região configurada)

Resposta:

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

---

list_objects

Lista objetos em um bucket com filtro de prefixo opcional.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
bucketName	string	✅	Bucket do qual listar objetos
prefix	string	❌	Filtrar por prefixo (caminho da pasta)
maxKeys	number	❌	Máximo de resultados (padrão: 1000)
continuationToken	string	❌	Token de paginação

---

upload_object

Envia um arquivo ou conteúdo de string para o S3.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
bucketName	string	✅	Bucket de destino
key	string	✅	Chave do objeto (caminho) no bucket
filePath	string	❌	Caminho do arquivo local a ser enviado
content	string	❌	Conteúdo de string para enviar diretamente
contentType	string	❌	Tipo MIME do conteúdo

---

download_object

Baixa um objeto do S3.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
bucketName	string	✅	Bucket de origem
key	string	✅	Chave do objeto (caminho) a ser baixado
outputPath	string	❌	Caminho local para salvar o arquivo
returnContent	boolean	❌	Retornar conteúdo inline na resposta

---

delete_object

Exclui um objeto de um bucket.

Parâmetros:

Nome	Tipo	Obrigatório	Descrição
bucketName	string	✅	Bucket que contém o objeto
key	string	✅	Chave do objeto a ser excluída

---

get_bucket_policy / set_bucket_policy

Obtém ou define a política IAM de um bucket.

Parâmetros para set_bucket_policy:

Nome	Tipo	Obrigatório	Descrição
bucketName	string	✅	Bucket de destino
policy	string/object	✅	Documento de política (string JSON ou objeto)

---

Autenticação AWS

O servidor usa a cadeia de resolução de credenciais do AWS SDK nesta ordem:

1. Variáveis de ambiente — AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
2. Arquivo de credenciais compartilhadas — ~/.aws/credentials (configurado via aws configure)
3. Metadados de instância EC2 — se estiver rodando em uma instância EC2 com função IAM

Para produção, funções IAM são recomendadas em vez de credenciais estáticas.

---

Contribuindo

Contribuições são bem-vindas! Se você quiser adicionar uma nova operação S3 ou melhorar as existentes:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade: git checkout -b feature/my-new-tool
3. Faça commit das suas alterações: git commit -m 'Add: new S3 tool'
4. Envie e abra um Pull Request

---

Licença

MIT — consulte LICENSE para detalhes.

---

Construído com o MCP TypeScript SDK e o AWS SDK v3.