金大哥 - s3-mcp-server MCP 详情

article

README

🚀 S3 MCP 服务器

S3 MCP 服务器是一个用于访问亚马逊 S3 存储桶的模型上下文协议（MCP）服务器。它通过 MCP 提供与 S3 存储的无缝集成，能够高效处理大文件，包括 PDF 文件，通过流式传输功能实现，为用户提供了便捷、高效的存储访问体验。

🚀 快速开始

S3 MCP 服务器通过 MCP 协议，实现了与 S3 存储的无缝集成，让你可以轻松访问和管理 S3 存储桶中的文件。它支持流式传输，能高效处理大文件，还具备多种实用功能和便捷的配置选项。

✨ 主要特性

带前缀过滤的 S3 桶对象列表：可根据前缀对 S3 桶中的对象进行过滤，方便快速定位所需文件。
通过流式传输高效处理大文件：利用流式传输功能，能够高效处理大文件，包括 PDF 文件，提升处理效率。
安全管理 AWS 凭据：保障 AWS 凭据的安全，防止信息泄露。
TypeScript 支持：支持 TypeScript 开发，提供更好的类型检查和开发体验。
带有自定义选项的 CLI 接口：提供命令行接口，支持自定义选项，方便用户根据需求进行配置。

📦 安装指南

使用以下命令安装 S3 MCP 服务器：

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

项目结构

.
├── src/              # TypeScript 源文件
├── dist/            # 编译后的 JavaScript 文件和运行时依赖项
├── tsconfig.json    # TypeScript 配置
└── package.json     # 项目配置和依赖关系

🚀 开发与部署

开发步骤

克隆仓库：

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

安装依赖项：

npm install

构建项目：

npm run build

本地运行：

node dist/cli.js

部署步骤

创建新版本标签：

npm version patch

推送到 npm 注册表：

npm publish --access public

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

📄 许可证

本项目采用 MIT 许可证。

💪 贡献

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

s3-mcp-server