{"_id":"@iflow-mcp/samuraikun-aws-s3-mcp","name":"@iflow-mcp/samuraikun-aws-s3-mcp","dist-tags":{"latest":"0.4.0"},"versions":{"0.4.0":{"name":"@iflow-mcp/samuraikun-aws-s3-mcp","version":"0.4.0","description":"MCP Server for S3","repository":{"type":"git","url":"git+https://github.com/samuraikun/aws-s3-mcp.git"},"main":"dist/index.js","bin":{"iflow-mcp-samuraikun-aws-s3-mcp":"dist/index.js"},"scripts":{"build":"tsc && chmod +x dist/index.js","start":"node dist/index.js","test":"vitest run","test:watch":"vitest","test:coverage":"vitest run --coverage","prepublish":"npm run build","lint":"npx @biomejs/biome lint .","format":"npx @biomejs/biome format . --write","check:format":"npx @biomejs/biome check .","docker:build":"docker build -t aws-s3-mcp .","docker:run":"docker run --rm --name aws-s3-mcp -p 3000:3000 aws-s3-mcp"},"keywords":["mcp","s3","aws","modelcontextprotocol"],"author":{"name":"Yuichi Kojima"},"license":"MIT","engines":{"node":">=18"},"dependencies":{"@aws-sdk/client-s3":"^3.806.0","@hono/node-server":"^1.14.3","@modelcontextprotocol/sdk":"^1.12.1","dotenv":"^16.5.0","hono":"^4.7.11","pdf-parse":"^1.1.1","ts-pattern":"^5.7.0","zod-to-json-schema":"^3.24.5"},"devDependencies":{"@biomejs/biome":"1.9.4","@types/node":"^22.15.17","@types/pdf-parse":"^1.1.5","@vitest/coverage-v8":"^3.1.3","aws-sdk-mock":"^6.2.1","typescript":"^5.8.3","vitest":"^3.1.3"},"_id":"@iflow-mcp/samuraikun-aws-s3-mcp@0.4.0","bugs":{"url":"https://github.com/samuraikun/aws-s3-mcp/issues"},"homepage":"https://github.com/samuraikun/aws-s3-mcp#readme","_integrity":"sha512-WWjZ20E/vEwmOYk1WZ2q1rEKWnt6g1buMd94urtSzRAbrIaWSy48R/ARBc07B7anmgtKHUaxiiBX13dsKNmVQg==","_resolved":"/app/auto-mcp-upload/data/12834/iflow-mcp-samuraikun-aws-s3-mcp-0.4.0.tgz","_from":"file:iflow-mcp-samuraikun-aws-s3-mcp-0.4.0.tgz","_nodeVersion":"24.13.0","_npmVersion":"11.6.2","dist":{"integrity":"sha512-WWjZ20E/vEwmOYk1WZ2q1rEKWnt6g1buMd94urtSzRAbrIaWSy48R/ARBc07B7anmgtKHUaxiiBX13dsKNmVQg==","shasum":"1ae5b68cb34038105bad99452013c59e17569217","tarball":"https://registry.npmjs.org/@iflow-mcp/samuraikun-aws-s3-mcp/-/samuraikun-aws-s3-mcp-0.4.0.tgz","fileCount":21,"unpackedSize":59425,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDTTrn+Gtb2Sp47MpyGGcjSHOh4/nRtmZw6uIIULNjvWQIgH2vVsIIaala+Cr6vfCxJ75NGYW6oUz3bq+3qHW7SKxU="}]},"_npmUser":{"name":"chatflowdev","email":"chatflowdev@gmail.com"},"directories":{},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/samuraikun-aws-s3-mcp_0.4.0_1772252847924_0.14540138074945785"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-28T04:27:27.821Z","0.4.0":"2026-02-28T04:27:28.074Z","modified":"2026-02-28T04:27:28.337Z"},"maintainers":[{"name":"chatflowdev","email":"chatflowdev@gmail.com"},{"name":"qystart","email":"987472953@qq.com"}],"description":"MCP Server for S3","homepage":"https://github.com/samuraikun/aws-s3-mcp#readme","keywords":["mcp","s3","aws","modelcontextprotocol"],"repository":{"type":"git","url":"git+https://github.com/samuraikun/aws-s3-mcp.git"},"author":{"name":"Yuichi Kojima"},"bugs":{"url":"https://github.com/samuraikun/aws-s3-mcp/issues"},"license":"MIT","readme":"# S3 MCP Server\n\n[![CI](https://img.shields.io/github/actions/workflow/status/samuraikun/aws-s3-mcp/test.yml?branch=main&style=flat-square&logo=github&label=tests)](https://github.com/samuraikun/aws-s3-mcp/actions/workflows/test.yml)\n[![Trivy Scan](https://img.shields.io/github/actions/workflow/status/samuraikun/aws-s3-mcp/docker.yml?branch=main&label=trivy&style=flat-square&logo=aquasecurity)](https://github.com/samuraikun/aws-s3-mcp/actions/workflows/docker.yml)\n[![npm version](https://img.shields.io/npm/v/aws-s3-mcp?style=flat-square&logo=npm)](https://www.npmjs.com/package/aws-s3-mcp)\n[![npm downloads](https://img.shields.io/npm/dm/aws-s3-mcp?style=flat-square&logo=npm)](https://www.npmjs.com/package/aws-s3-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/aws-s3-mcp?style=flat-square&logo=nodedotjs)](https://nodejs.org/)\n\nAn Amazon S3 Model Context Protocol (MCP) server that provides tools for interacting with S3 buckets and objects.\n\nhttps://github.com/user-attachments/assets/d05ff0f1-e2bf-43b9-8d0c-82605abfb666\n\n## Features\n\n### 🚀 MCP Transport Support\n\n- ✅ **STDIO Transport** - Direct process communication for Claude Desktop\n- ✅ **HTTP Transport** - REST API with Server-Sent Events for web clients\n- ✅ **Streamable HTTP** - Real-time streaming for responsive interactions\n\n### 🛠️ Available Tools\n\n- ✅ **list-buckets** - List accessible S3 buckets with filtering\n- ✅ **list-objects** - Browse objects within buckets with prefix filtering\n- ✅ **get-object** - Retrieve object contents (text/binary support)\n\n### 🐳 Deployment Options\n\n- ✅ **Local Node.js** - Direct execution with npm/node\n- ✅ **Docker CLI** - Containerized deployment with custom configuration\n- ✅ **Docker Compose** - Full stack with MinIO for local testing\n- ✅ **MCP Inspector** - Built-in debugging and testing interface\n\n## Overview\n\nThis MCP server allows Large Language Models (LLMs) like Claude to interact with AWS S3 storage. It provides tools for:\n\n- Listing available S3 buckets\n- Listing objects within a bucket\n- Retrieving object contents\n\nThe server is built using TypeScript and the MCP SDK, providing a secure and standardized way for LLMs to interface with S3.\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18 or higher\n- npm or yarn\n- AWS credentials configured (either through environment variables or AWS credentials file)\n- Docker (optional, for containerized setup)\n\n### Setup\n\n1. Install via npm:\n\n```bash\n# Install globally via npm\nnpm install -g aws-s3-mcp\n\n# Or as a dependency in your project\nnpm install aws-s3-mcp\n```\n\n2. If building from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/samuraikun/aws-s3-mcp.git\ncd aws-s3-mcp\n\n# Install dependencies and build\nnpm install\nnpm run build\n```\n\n3. Configure AWS credentials and S3 access:\n\nCreate a `.env` file with your AWS configuration:\n\n```\nAWS_REGION=us-east-1\nS3_BUCKETS=bucket1,bucket2,bucket3\nS3_MAX_BUCKETS=5\nAWS_ACCESS_KEY_ID=your-access-key\nAWS_SECRET_ACCESS_KEY=your-secret-key\n```\n\nOr set these as environment variables.\n\n## Configuration\n\nThe server can be configured using the following environment variables:\n\n| Variable                | Description                                       | Default           |\n| ----------------------- | ------------------------------------------------- | ----------------- |\n| `AWS_REGION`            | AWS region where your S3 buckets are located      | `us-east-1`       |\n| `S3_BUCKETS`            | Comma-separated list of allowed S3 bucket names   | (empty)           |\n| `S3_MAX_BUCKETS`        | Maximum number of buckets to return in listing    | `5`               |\n| `AWS_ACCESS_KEY_ID`     | AWS access key (if not using default credentials) | (from AWS config) |\n| `AWS_SECRET_ACCESS_KEY` | AWS secret key (if not using default credentials) | (from AWS config) |\n\n## Running the Server\n\n### Direct Node.js Execution\n\nThe server runs with **HTTP transport by default**, making it easy to test and debug:\n\n```bash\n# Using npx (HTTP transport by default)\nnpx aws-s3-mcp\n\n# If installed globally (HTTP transport)\nnpm install -g aws-s3-mcp\naws-s3-mcp\n\n# If running from cloned repository (HTTP transport)\nnpm start\n\n# Or directly (HTTP transport)\nnode dist/index.js\n\n# Explicit HTTP transport\nnode dist/index.js --http\n\n# STDIO transport (for Claude Desktop integration)\nnode dist/index.js --stdio\n```\n\nWhen running with HTTP transport (default), the server will start on port 3000 and provide:\n\n- Health check endpoint: `http://localhost:3000/health`\n- MCP endpoint: `http://localhost:3000/mcp`\n- SSE endpoint: `http://localhost:3000/sse`\n\n### Docker Setup 🐳\n\nYou can run the S3 MCP server as a Docker container using either Docker CLI or Docker Compose.\n\n#### Using Docker CLI\n\n1. Build the Docker image:\n\n```bash\ndocker build -t aws-s3-mcp .\n```\n\n2. Run the container with environment variables:\n\n```bash\n# Option 1: Pass environment variables directly\ndocker run -d \\\n  -e AWS_REGION=us-east-1 \\\n  -e S3_BUCKETS=bucket1,bucket2 \\\n  -e S3_MAX_BUCKETS=5 \\\n  -e AWS_ACCESS_KEY_ID=your-access-key \\\n  -e AWS_SECRET_ACCESS_KEY=your-secret-key \\\n  --name aws-s3-mcp-server \\\n  aws-s3-mcp\n\n# Option 2: Use environment variables from .env file\ndocker run -d \\\n  --env-file .env \\\n  --name aws-s3-mcp-server \\\n  aws-s3-mcp\n```\n\n3. Check container logs:\n\n```bash\ndocker logs aws-s3-mcp-server\n```\n\n4. Stop and remove the container:\n\n```bash\ndocker stop aws-s3-mcp-server\ndocker rm aws-s3-mcp-server\n```\n\nNote: For HTTP transport (default), add `-p 3000:3000` to expose the HTTP port. For STDIO transport (Claude Desktop), no port mapping is needed as it uses Docker exec for direct communication.\n\n#### Using Docker Compose\n\n1. Build and start the Docker container:\n\n```bash\n# Build and start the container\ndocker compose up -d s3-mcp\n\n# View logs\ndocker compose logs -f s3-mcp\n```\n\n2. To stop the container:\n\n```bash\ndocker compose down\n```\n\n#### Using Docker with MinIO for Testing\n\nThe Docker Compose setup includes a MinIO service for local testing:\n\n```bash\n# Start MinIO and the MCP server\ndocker compose up -d\n\n# Access MinIO console at http://localhost:9001\n# Default credentials: minioadmin/minioadmin\n```\n\nThe MinIO service automatically creates two test buckets (`test-bucket-1` and `test-bucket-2`) and uploads sample files for testing.\n\n## Debugging with MCP Inspector 🔍\n\nThe `run-inspector.sh` script provides an easy way to test and debug the S3 MCP server using the MCP Inspector. It supports multiple transport types and deployment modes.\n\n### Quick Start\n\n```bash\n# Show all available options\n./run-inspector.sh --help\n\n# Run locally with HTTP transport (default)\n./run-inspector.sh\n\n# Run with Docker Compose and MinIO for testing\n./run-inspector.sh --docker-compose\n```\n\n### Transport Types\n\nThe server supports two transport protocols:\n\n#### HTTP Transport\n\n- **Best for**: Web-based debugging, external client connections\n- **Provides**: REST API endpoints, Server-Sent Events (SSE)\n- **Ports**: 3000 (HTTP), 3001+ (Inspector UI)\n\n#### STDIO Transport\n\n- **Best for**: Direct process communication, Claude Desktop integration\n- **Provides**: Standard input/output communication\n- **Ports**: None (direct process communication)\n\n### Usage Examples\n\n#### 1. Local Development (HTTP)\n\n```bash\n# Default: HTTP transport for local debugging\n./run-inspector.sh\n\n# Explicit HTTP transport\n./run-inspector.sh --http\n```\n\nThis will:\n\n- Build the project if needed\n- Start the MCP server with HTTP transport on port 3000\n- Launch MCP Inspector in your browser\n- Provide endpoints:\n  - Health check: `http://localhost:3000/health`\n  - MCP endpoint: `http://localhost:3000/mcp`\n  - SSE endpoint: `http://localhost:3000/sse`\n\n#### 2. Local Development (STDIO)\n\n```bash\n# STDIO transport for local debugging\n./run-inspector.sh --stdio\n```\n\nThis mode directly connects the MCP Inspector to the server process using standard input/output.\n\n#### 3. Docker with Real AWS (STDIO)\n\n```bash\n# Create .env file with your AWS credentials\ncp .env.example .env\n# Edit .env with your AWS credentials\n\n# Run with Docker using STDIO transport (default for Docker)\n./run-inspector.sh --docker\n```\n\nThis will:\n\n- Build the Docker image if needed\n- Start a container with your AWS credentials\n- Connect MCP Inspector via Docker exec\n\n#### 4. Docker with Real AWS (HTTP)\n\n```bash\n# Run with Docker using HTTP transport\n./run-inspector.sh --docker --http\n```\n\nThis will:\n\n- Start a containerized HTTP server on port 3000\n- Connect MCP Inspector to the HTTP endpoint\n- Useful for testing HTTP-based integrations\n\n#### 5. Docker Compose with MinIO (Testing)\n\n```bash\n# Run with MinIO for local testing (no AWS credentials needed)\n./run-inspector.sh --docker-compose\n```\n\nThis will:\n\n- Start MinIO S3-compatible storage\n- Create test buckets: `test-bucket-1`, `test-bucket-2`\n- Upload sample files for testing\n- Start the S3 MCP server connected to MinIO\n- Launch MCP Inspector\n- Provide MinIO Web UI at `http://localhost:9001` (login: minioadmin/minioadmin)\n\n### Advanced Options\n\n#### Force Rebuild\n\n```bash\n# Force Docker image rebuild\n./run-inspector.sh --docker --force-rebuild\n./run-inspector.sh --docker-compose --force-rebuild\n```\n\n#### Debugging Tips\n\n1. **Check container logs**:\n\n   ```bash\n   # For Docker CLI mode\n   docker logs aws-s3-mcp-server\n\n   # For Docker Compose mode\n   docker compose logs s3-mcp\n   ```\n\n2. **Test endpoints manually**:\n\n   ```bash\n   # Health check\n   curl http://localhost:3000/health\n\n   # MinIO health (Docker Compose)\n   curl http://localhost:9000/minio/health/live\n   ```\n\n3. **Access MinIO Web UI** (Docker Compose only):\n   - URL: `http://localhost:9001`\n   - Username: `minioadmin`\n   - Password: `minioadmin`\n\n### Cleanup\n\n```bash\n# Stop and remove Docker containers\ndocker stop aws-s3-mcp-server && docker rm aws-s3-mcp-server\n\n# Stop Docker Compose services\ndocker compose down\n\n# Stop specific HTTP server container\ndocker stop aws-s3-mcp-http-server && docker rm aws-s3-mcp-http-server\n```\n\n### Troubleshooting\n\n- **Port conflicts**: If port 3000 is in use, stop other services or change the port\n- **AWS credentials**: Ensure your `.env` file has valid AWS credentials for Docker modes\n- **Build errors**: Use `--force-rebuild` to rebuild Docker images\n- **Connection issues**: Check that containers are running with `docker ps`\n\n### Quick Reference\n\n| Command                               | Transport | Environment    | Description                              |\n| ------------------------------------- | --------- | -------------- | ---------------------------------------- |\n| `./run-inspector.sh`                  | HTTP      | Local          | Local development with HTTP transport    |\n| `./run-inspector.sh --stdio`          | STDIO     | Local          | Local development with STDIO transport   |\n| `./run-inspector.sh --docker`         | STDIO     | Docker + AWS   | Docker container with AWS credentials    |\n| `./run-inspector.sh --docker --http`  | HTTP      | Docker + AWS   | Docker container with HTTP transport     |\n| `./run-inspector.sh --docker-compose` | STDIO     | Docker + MinIO | Local testing with MinIO (no AWS needed) |\n\n## Connecting to Claude Desktop\n\nTo use this server with Claude Desktop, you'll need to use **STDIO transport** (not the default HTTP transport) for direct process communication:\n\n1. Edit your Claude Desktop configuration file:\n\n   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n   - Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n2. Add the S3 MCP server to the configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"s3\": {\n      \"command\": \"npx\",\n      \"args\": [\"aws-s3-mcp\", \"--stdio\"],\n      \"env\": {\n        \"AWS_REGION\": \"us-east-1\",\n        \"S3_BUCKETS\": \"bucket1,bucket2,bucket3\",\n        \"S3_MAX_BUCKETS\": \"5\",\n        \"AWS_ACCESS_KEY_ID\": \"your-access-key\",\n        \"AWS_SECRET_ACCESS_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n### Docker Option for Claude Desktop 🐳\n\nYou can also configure Claude Desktop to use a running Docker container for the MCP server:\n\n```json\n{\n  \"mcpServers\": {\n    \"s3\": {\n      \"command\": \"docker\",\n      \"args\": [\"exec\", \"-i\", \"aws-s3-mcp-server\", \"node\", \"dist/index.js\"],\n      \"env\": {}\n    }\n  }\n}\n```\n\n> **⚠️ Important Prerequisites**: For this Docker configuration to work, you **MUST** first build and run the Docker container **BEFORE** launching Claude Desktop:\n>\n> ```bash\n> # 1. First, build the Docker image (only needed once or after changes)\n> docker build -t aws-s3-mcp .\n>\n> # 2. Then start the container (required each time before using with Claude)\n> # Using Docker Compose (recommended)\n> docker compose up -d s3-mcp\n>\n> # Or using Docker CLI\n> docker run -d --name aws-s3-mcp-server --env-file .env aws-s3-mcp\n> ```\n>\n> Without a running container, Claude Desktop will show errors when trying to use S3 tools.\n>\n> The Docker configuration above uses `exec` to send MCP requests directly to the running container. No port mapping is required since Claude communicates directly with the container instead of through a network port.\n\n> **Note**: Ensure the container name in the configuration (`aws-s3-mcp-server`) matches the name of your running container.\n\n> **Important**: Please note the following when using the configuration above\n>\n> - Replace `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with your actual credentials\n> - `S3_BUCKETS` should contain a comma-separated list of buckets you want to allow access to\n> - `AWS_REGION` should be set to the region where your buckets are located\n\n### 💣 If error occurs on Claude Desktop\n\nIf you encounter errors with the above configuration in Claude Desktop, try using absolute paths as follows:\n\n```bash\n# Get the path of node and aws-s3-mcp\nwhich node\nwhich aws-s3-mcp\n```\n\n```json\n{\n  \"globalShortcut\": \"\",\n  \"mcpServers\": {\n    \"s3\": {\n      \"command\": \"your-absolute-path-to-node\",\n      \"args\": [\"your-absolute-path-to-aws-s3-mcp/dist/index.js\", \"--stdio\"],\n      \"env\": {\n        \"AWS_REGION\": \"your-aws-region\",\n        \"S3_BUCKETS\": \"your-s3-buckets\",\n        \"S3_MAX_BUCKETS\": \"your-max-buckets\",\n        \"AWS_ACCESS_KEY_ID\": \"your-access-key\",\n        \"AWS_SECRET_ACCESS_KEY\": \"your-secret-key\"\n      }\n    }\n  }\n}\n```\n\n## Available Tools\n\n### list-buckets\n\nLists available S3 buckets that the server has permission to access. This tool respects the `S3_BUCKETS` configuration that limits which buckets are shown.\n\n**Parameters:** None\n\n**Example output:**\n\n```json\n[\n  {\n    \"Name\": \"my-images-bucket\",\n    \"CreationDate\": \"2022-03-15T10:30:00.000Z\"\n  },\n  {\n    \"Name\": \"my-documents-bucket\",\n    \"CreationDate\": \"2023-05-20T14:45:00.000Z\"\n  }\n]\n```\n\n### list-objects\n\nLists objects in a specified S3 bucket.\n\n**Parameters:**\n\n- `bucket` (required): Name of the S3 bucket to list objects from\n- `prefix` (optional): Prefix to filter objects (like a folder path)\n- `maxKeys` (optional): Maximum number of objects to return\n\n**Example output:**\n\n```json\n[\n  {\n    \"Key\": \"sample.pdf\",\n    \"LastModified\": \"2023-10-10T08:12:15.000Z\",\n    \"Size\": 2048576,\n    \"StorageClass\": \"STANDARD\"\n  },\n  {\n    \"Key\": \"sample.md\",\n    \"LastModified\": \"2023-10-12T15:30:45.000Z\",\n    \"Size\": 1536000,\n    \"StorageClass\": \"STANDARD\"\n  }\n]\n```\n\n### get-object\n\nRetrieves an object from a specified S3 bucket. Text files are returned as plain text, while binary files are returned with limited details.\n\n**Parameters:**\n\n- `bucket` (required): Name of the S3 bucket\n- `key` (required): Key (path) of the object to retrieve\n\n**Example text output:**\n\n```\nThis is the content of a text file stored in S3.\nIt could be JSON, TXT, CSV or other text-based formats.\n```\n\n**Example binary output:**\n\n```\nBinary content (image/jpeg): base64 data is /9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRof...\n```\n\n## Security Considerations\n\n- The server will only access buckets specified in the `S3_BUCKETS` environment variable\n- AWS credentials must have appropriate permissions to the buckets\n- Use the principle of least privilege when configuring AWS permissions\n- For production use, consider using IAM roles with specific S3 permissions\n\n## Usage with Claude\n\nWhen interacting with Claude in the desktop app, you can ask it to perform S3 operations like:\n\n- \"List all my S3 buckets\"\n- \"Summarize PDF files in my-documents-bucket\"\n- \"Get the README.txt file from my-documents-bucket\"\n\nClaude will use the appropriate MCP tool to carry out the request and show you the results.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-ba196208b4074d4e685b7b6996a0e30d"}