S3 MCP 서버

Name: S3 MCP Server
Author: samuraikun

씨아이 트리비 스캔 npm 버전 npm 다운로드 라이센스: MIT Node.js 버전

S3 버킷 및 객체와 상호 작용하기 위한 도구를 제공하는 Amazon S3 모델 컨텍스트 프로토콜(MCP) 서버입니다.

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

개요

이 MCP 서버는 Claude와 같은 대규모 언어 모델(LLM)이 AWS S3 스토리지와 상호 작용할 수 있도록 지원합니다. 다음과 같은 도구를 제공합니다.

사용 가능한 S3 버킷 나열
버킷 내의 객체 나열
객체 내용 검색

이 서버는 TypeScript와 MCP SDK를 사용하여 구축되었으며, LLM이 S3와 상호 작용하는 안전하고 표준화된 방법을 제공합니다.

Related MCP server: AWS MCP Server

설치

필수 조건

Node.js 18 이상
npm 또는 yarn
AWS 자격 증명이 구성됨(환경 변수 또는 AWS 자격 증명 파일을 통해)
Docker(컨테이너화된 설정을 위한 선택 사항)

설정

npm을 통해 설치:

지엑스피1

소스에서 빌드하는 경우:

# 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 액세스를 구성합니다.

AWS 구성을 사용하여 .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

또는 이를 환경 변수로 설정합니다.

구성

다음 환경 변수를 사용하여 서버를 구성할 수 있습니다.

변하기 쉬운	설명	기본
`AWS_REGION`	S3 버킷이 있는 AWS 지역	`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 설정 🐳

Docker CLI 또는 Docker Compose를 사용하여 S3 MCP 서버를 Docker 컨테이너로 실행할 수 있습니다.

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

컨테이너는 Docker exec를 통해 Claude Desktop과 함께 사용하도록 설계되었기 때문에 어떤 포트도 노출하지 않으며, 직접 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

테스트를 위해 MinIO와 함께 Docker 사용

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 서버 컨테이너가 실행 중이 아니면 시작합니다.
S3 MCP 서버에 연결된 MCP Inspector를 실행합니다.
그런 다음 로컬 MinIO 인스턴스에 대해 S3 도구를 테스트할 수 있습니다.

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

Claude Desktop용 Docker 옵션 🐳

MCP 서버에 실행 중인 Docker 컨테이너를 사용하도록 Claude Desktop을 구성할 수도 있습니다.

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

⚠️ 중요 전제 조건 : 이 Docker 구성이 작동하려면 Claude Desktop을 시작하기 전에 먼저 Docker 컨테이너를 빌드하고 실행 해야 합니다 .
# 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" } ]

get-object

지정된 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 권한을 구성할 때 최소 권한 원칙을 사용하세요.
프로덕션 용도로는 특정 S3 권한이 있는 IAM 역할을 사용하는 것이 좋습니다.

Claude와 함께 사용

데스크톱 앱에서 Claude와 상호 작용할 때 다음과 같은 S3 작업을 수행하도록 요청할 수 있습니다.

"내 S3 버킷 모두 나열"
"내 문서 버킷에 있는 PDF 파일 요약"
"my-documents-bucket에서 README.txt 파일을 가져옵니다"

클로드는 적절한 MCP 도구를 사용하여 요청을 수행하고 결과를 보여드립니다.

특허

MIT

S3 MCP Server