S3 MCP Server

🚀 S3 MCP Server

An MCP (Model Context Protocol) server for accessing Amazon S3 buckets. This server provides seamless integration with S3 storage via MCP, enabling efficient handling of large files, including PDF files, through streaming capabilities.

✨ Features

• List S3 bucket objects with prefix filtering.
• Efficiently handle large files via streaming.
• Securely manage AWS credentials.
• Support for TypeScript.
• CLI interface with custom options.

📦 Installation

npx -y @geunoh/s3-mcp-server

💻 Usage Examples

CLI Options

npx -y @geunoh/s3-mcp-server [options]

Options:

• --port, -p: Server port (Default: 3000)
• --region, -r: AWS region (Default: ap-northeast-2)
• --bucket, -b: S3 bucket name (Default: my-dancing-bucket)

Environment Variables

Required:

export AWS_ACCESS_KEY_ID="your_access_key"
export AWS_SECRET_ACCESS_KEY="your_secret_key"

Optional:

export AWS_REGION="ap-northeast-2"
export S3_BUCKET_NAME="my-bucket-name"

MCP Integration

Add the following to mcp.json:

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "npx",
      "args": ["-y", "@geunoh/s3-mcp-server"],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY",

        // Optional
        "AWS_REGION": "ap-northeast-2",
        "S3_BUCKET_NAME": "my-bucket-name"
      }
    }
  }
}

Available MCP Functions

listObjects

List objects in the S3 bucket. Parameters:

• prefix (Optional): Filter objects by prefix.

getObject

Retrieve an object from the S3 bucket. Optimized for large files via streaming. Parameters:

• key: The key of the object to retrieve. Return values:
• stream: A ReadableStream of the object content.
• contentType: The MIME type of the object.
• contentLength: The size of the object in bytes.
• lastModified: The last modified timestamp.
• text: The ByteArray text buffer of the original PDF.

🔧 Technical Details

AWS IAM Permissions

The minimum required permissions (see s3-policy.json):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::my-bucket-name"
        }
    ]
}

Development

1. Clone the repository:

git clone https://github.com/Geun-Oh/s3-mcp-server.git
cd s3-mcp-server

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run locally:

node dist/cli.js

Project Structure

.
├── src/              # TypeScript source files
├── dist/            # Compiled JavaScript files and runtime dependencies
├── tsconfig.json    # TypeScript configuration
└── package.json     # Project configuration and dependencies

Deployment

1. Create a new version tag:

npm version patch

2. Push to the npm registry:

npm publish --access public

The GitHub Actions workflow will automatically publish the package when a new version tag is pushed.

📄 License

MIT

Contribution

For contributions, please refer to the contribution guidelines in the project repository.