s3-mcp-server
If you are the rightful owner of s3-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A Model Context Protocol (MCP) server for accessing Amazon S3 buckets, providing seamless integration with S3 storage through MCP.
S3 MCP Server
A Model Context Protocol (MCP) server for accessing Amazon S3 buckets. This server provides seamless integration with S3 storage through MCP, allowing efficient handling of large files including PDFs through streaming capabilities.
Features
- S3 bucket object listing with prefix filtering
- Efficient large file handling through streaming
- Secure AWS credentials management
- TypeScript support
- CLI interface with customizable options
Installation
npx -y @geunoh/s3-mcp-server
Usage
Command Line 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 to your mcp.json:
{
"mcpServers": {
"s3-mcp-server": {
"command": "npx",
"args": ["-y", "@geunoh/s3-mcp-server", "--region", "us-east-1", "--bucket", "my-test-bucket"],
"env": {
"AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
"AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY",
}
}
}
}
Or like this way:
{
"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": "us-east-1",
"S3_BUCKET_NAME": "my-test-bucket",
}
}
}
}
Available MCP Functions
listObjects
Lists objects in the S3 bucket.
Parameters:
prefix(optional): Filter objects by prefix
getObject
Retrieves an object from the S3 bucket. Optimized for large files through streaming.
Parameters:
key: The key of the object to retrieve
Returns:
stream: ReadableStream of the object contentcontentType: MIME type of the objectcontentLength: Size of the object in byteslastModified: Last modification timestamptext: Text buffer of raw pdf ByteArray
AWS IAM Permissions
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
- Clone the repository:
git clone https://github.com/Geun-Oh/s3-mcp-server.git
cd s3-mcp-server
- Install dependencies:
npm install
- Build the project:
npm run build
- 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
- Create a new version tag:
npm version patch
- Push to npm registry:
npm publish --access public
The GitHub Actions workflow will automatically publish the package when a new version tag is pushed.
License
MIT
Contributing
Issues and pull requests are welcome. Please ensure that your changes maintain the existing code style and include appropriate tests.
