S3 MCP 服务器

一个用于访问亚马逊 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）

环境变量

所需：

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"

MCP 集成

在 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",

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

可用 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 源文件
├── dist/            # 编译后的 JavaScript 文件和运行时依赖项
├── tsconfig.json    # TypeScript 配置
└── package.json     # 项目配置和依赖关系

部署

1. 创建新版本标签：

npm version patch

2. 推送到 npm 注册表：

npm publish --access public

GitHub Actions 工作流会在推送新的版本标签时自动发布包。

许可证

MIT

贡献

如需贡献，请参考项目仓库中的贡献指南。