S3 MCP-сервер

Trivy Скан npm-версия npm-загрузки Лицензия: Массачусетский технологический институт Версия Node.js

Сервер 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 (опционально, для контейнерной установки)

Настраивать

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

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

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

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

# 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

Настройте учетные данные 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

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

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

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

Переменная	Описание	По умолчанию
`AWS_REGION`	Регион AWS, где расположены ваши контейнеры S3	`us-east-1`
`S3_BUCKETS`	Список разрешенных имен контейнеров S3, разделенных запятыми	(пустой)
`S3_MAX_BUCKETS`	Максимальное количество сегментов для возврата в листинге	`5`
`AWS_ACCESS_KEY_ID`	Ключ доступа AWS (если не используются учетные данные по умолчанию)	(из конфигурации AWS)
`AWS_SECRET_ACCESS_KEY`	Секретный ключ AWS (если не используются учетные данные по умолчанию)	(из конфигурации AWS)

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

Прямое выполнение 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

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

docker build -t aws-s3-mcp .

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

# 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

Проверьте журналы контейнера:

docker logs aws-s3-mcp-server

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

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

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

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

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

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

# View logs
docker compose logs -f s3-mcp

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

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 скрипт выполнит следующие действия:

Запустите контейнеры MinIO и сервера S3 MCP, если они не запущены.
Запустите MCP Inspector, подключенный к серверу S3 MCP.
Затем вы можете протестировать инструменты S3 на локальном экземпляре MinIO.

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

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

Отредактируйте файл конфигурации Claude Desktop:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Добавьте сервер 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 для выполнения запроса и покажет вам результаты.

Лицензия

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

S3 MCP Server