S3 MCP Server

S3 MCP Server

用于访问 Amazon S3 存储桶的模型上下文协议（MCP）服务。此服务通过 MCP 与 S3 存储无缝集成，并支持流式处理，从而高效处理包括 PDF 在内的大型文件。

功能

• 按前缀筛选 S3 存储桶对象列表
• 通过流式处理高效处理大型文件
• 安全管理 AWS 凭证
• 支持 TypeScript
• 提供可自定义选项的 CLI 界面

安装

npx -y @geunoh/s3-mcp-server

用法

命令行选项

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

选项：

• --port, -p：服务端口（默认值：3000）
• --region, -r：AWS 区域（默认值：ap-northeast-2）
• --bucket, -b：S3 存储桶名称（默认值：my-dancing-bucket）
• --content-type, -t：上传/下载时输入文件的内容类型（默认值：application/octet-stream）

环境变量

必需：

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

可选：

export AWS_REGION="ap-northeast-2"
export S3_BUCKET_NAME="my-bucket-name"
export CONTENT_TYPE="application/octet-stream" # Optional: default MIME type for uploads/downloads

MCP 集成

添加到你的 mcp.json：

{
  "mcpServers": {
    "s3-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@geunoh/s3-mcp-server",
        "--region",
        "us-east-1",
        "--bucket",
        "my-test-bucket",
        "--content-type",
        "text/plain"
      ],
      "env": {
        "AWS_ACCESS_KEY_ID": "YOUR_AWS_ACCESS_KEY_ID",
        "AWS_SECRET_ACCESS_KEY": "YOUR_AWS_SECRET_ACCESS_KEY"
      }
    }
  }
}

或者使用以下方式：

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

可用的 MCP 函数

listObjects

列出 S3 存储桶中的对象。

参数：

• prefix（可选）：按前缀筛选对象

getObject

从 S3 存储桶中获取对象。通过流式处理优化大型文件的获取。

参数：

• key：要获取的对象的键

返回值：

• stream：对象内容的 ReadableStream
• contentType：对象的 MIME 类型
• contentLength：对象的大小（字节）
• lastModified：最后修改时间戳
• text：原始 PDF ByteArray 的文本缓冲区

AWS IAM 权限

最低所需权限（参见 s3-policy.json）：

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

开发

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目：

npm run build

4. 在本地运行：

node dist/cli.js

项目结构

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

部署

1. 创建新的版本标签：

npm version patch

2. 推送到 npm 注册表：

npm publish --access public

推送新的版本标签后，GitHub Actions 工作流将自动发布此软件包。

许可证

MIT

贡献

欢迎提交问题和拉取请求。请确保你的更改遵循现有代码风格，并包含适当的测试。