S3 MCP 服务器

一个用于访问 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)

环境变量

必需：

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

        // optional
        "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

贡献

欢迎提交 Issues 和 Pull Requests。请确保您的更改保持现有的代码风格，并包含适当的测试。