S3 MCP-сервер

Сервер Amazon S3 Model Context Protocol (MCP), предоставляющий инструменты для взаимодействия с контейнерами и объектами S3.

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

Обзор

Этот сервер MCP позволяет большим языковым моделям (LLM), таким как Claude, взаимодействовать с хранилищем AWS S3. Он предоставляет инструменты для:

• Список доступных S3-корзин

• Перечисление объектов в контейнере

• Извлечение содержимого объекта

Сервер создан с использованием TypeScript и MCP SDK, что обеспечивает безопасный и стандартизированный способ взаимодействия LLM с S3.

Related MCP server: AWS MCP Server

Установка

Предпосылки

• Node.js 18 или выше

• npm или пряжа

• Настроенные учетные данные AWS (через переменные среды или файл учетных данных AWS)

• Docker (опционально, для контейнерной установки)

Настраивать

1. Установить через npm:

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

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

2. Если сборка из исходного кода:

# 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. Настройте учетные данные AWS и доступ к S3:

Создайте файл .env с вашей конфигурацией 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

Или установите их как переменные среды.

Конфигурация

Сервер можно настроить с помощью следующих переменных среды:

Запуск сервера

Прямое выполнение Node.js

Вы можете запустить сервер напрямую с 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

Настройка Docker 🐳

Вы можете запустить сервер S3 MCP как контейнер Docker, используя Docker CLI или Docker Compose.

Использование Docker CLI

1. Создайте образ Docker:

docker build -t aws-s3-mcp .

2. Запустите контейнер с переменными среды:

# 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. Проверьте журналы контейнера:

docker logs aws-s3-mcp-server

4. Остановитесь и удалите контейнер:

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

Обратите внимание, что контейнер не предоставляет никаких портов, поскольку он предназначен для использования с Claude Desktop через Docker exec, а не через прямые HTTP-соединения.

Использование Docker Compose

1. Соберите и запустите Docker-контейнер:

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

# View logs
docker compose logs -f s3-mcp

2. Чтобы остановить контейнер:

docker compose down

Использование Docker с MinIO для тестирования

Настройка Docker Compose включает службу MinIO для локального тестирования:

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

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

Служба MinIO автоматически создает два тестовых контейнера ( test-bucket-1 и test-bucket-2 ) и загружает файлы образцов для тестирования.

Отладка в MCP Inspector

Для отладки сервера с помощью 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

При использовании опции --docker-compose скрипт выполнит следующие действия:

1. Запустите контейнеры MinIO и сервера S3 MCP, если они не запущены.

2. Запустите MCP Inspector, подключенный к серверу S3 MCP.

3. Затем вы можете протестировать инструменты S3 на локальном экземпляре MinIO.

Подключение к Claude Desktop

Чтобы использовать этот сервер с Claude Desktop:

1. Отредактируйте файл конфигурации Claude Desktop:

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

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

2. Добавьте сервер S3 MCP в конфигурацию:

{
  "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 для Claude Desktop 🐳

Вы также можете настроить Claude Desktop для использования работающего контейнера Docker для сервера MCP:

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

⚠️ Важные предварительные условия : для работы этой конфигурации Docker вам СЛЕДУЕТ сначала собрать и запустить контейнер Docker ПЕРЕД запуском 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

Без запущенного контейнера Claude Desktop будет выдавать ошибки при попытке использования инструментов S3.

Конфигурация Docker выше использует exec для отправки запросов MCP напрямую в работающий контейнер. Сопоставление портов не требуется, поскольку Claude взаимодействует с контейнером напрямую, а не через сетевой порт.

Примечание : убедитесь, что имя контейнера в конфигурации ( aws-s3-mcp-server ) совпадает с именем запущенного контейнера.

Важно : при использовании указанной выше конфигурации обратите внимание на следующее:

• Замените AWS_ACCESS_KEY_ID и AWS_SECRET_ACCESS_KEY на ваши фактические учетные данные.

• S3_BUCKETS должен содержать список контейнеров, разделенных запятыми, к которым вы хотите разрешить доступ.

• AWS_REGION должен быть установлен на регион, где расположены ваши контейнеры.

💣 Если возникла ошибка на Claude Desktop

Если вы столкнулись с ошибками в приведенной выше конфигурации в Claude Desktop, попробуйте использовать абсолютные пути следующим образом:

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

Доступные инструменты

список-ведра

Перечисляет доступные S3-корзины, к которым у сервера есть разрешение на доступ. Этот инструмент учитывает конфигурацию S3_BUCKETS , которая ограничивает отображаемые корзинки.

Параметры: Нет

Пример вывода:

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

список-объектов

Перечисляет объекты в указанном контейнере S3.

Параметры:

• bucket (обязательно): Имя корзины S3, из которой нужно получить список объектов.

• prefix (необязательно): префикс для фильтрации объектов (например, путь к папке)

• maxKeys (необязательно): максимальное количество возвращаемых объектов.

Пример вывода:

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

получить-объект

Извлекает объект из указанного контейнера S3. Текстовые файлы возвращаются как обычный текст, а двоичные файлы возвращаются с ограниченными подробностями.

Параметры:

• bucket (обязательно): Имя ведра S3

• key (обязательно): Ключ (путь) объекта для извлечения

Пример текстового вывода:

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

Пример двоичного вывода:

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

Соображения безопасности

• Сервер будет иметь доступ только к тем контейнерам, которые указаны в переменной среды S3_BUCKETS .

• Учетные данные AWS должны иметь соответствующие разрешения для корзин

• Используйте принцип наименьших привилегий при настройке разрешений AWS.

• Для использования в производственной среде рассмотрите возможность использования ролей IAM с определенными разрешениями S3.

Использование с Клодом

При взаимодействии с Клодом в настольном приложении вы можете попросить его выполнить такие операции S3, как:

• «Список всех моих S3-корзин»

• «Обобщить файлы PDF в корзине my-documents»

• "Получить файл README.txt из my-documents-bucket"

Клод воспользуется соответствующим инструментом MCP для выполнения запроса и покажет вам результаты.

Лицензия

Массачусетский технологический институт