S3 MCP 服务器

这是一个通过 Model Context Protocol (MCP) 访问 Amazon S3 存储桶的服务器。该服务器通过 MCP 提供与 S3 存储的无缝集成，允许通过流媒体功能高效处理包括 PDF 在内的大文件。

特性

• 带有前缀过滤的 S3 存储桶对象列表
• 通过流媒体功能高效处理大文件
• 安全的 AWS 凭证管理
• 支持 TypeScript
• 带有可定制选项的命令行界面

安装

npx -y @geunoh/s3-mcp-server

使用

命令行选项

npx -y @geunoh/s3-mcp-server [选项]

选项：

• --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" # 可选：上传/下载时默认的 MIME 类型

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

        // 可选
        "AWS_REGION": "us-east-1",
        "S3_BUCKET_NAME": "my-test-bucket"
      }
    }
  }
}

可用的 MCP 函数

listObjects

列出 S3 存储桶中的对象。

参数：

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

getObject

从 S3 存储桶中检索对象。通过流媒体功能优化大文件的处理。

参数：

• key: 要检索的对象的键

返回值：

• stream: 对象内容的可读流
• contentType: 对象的 MIME 类型
• contentLength: 对象的大小（以字节为单位）
• lastModified: 最后修改时间戳
• text: 原始 PDF 字节数组的文本缓冲区

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

贡献

欢迎提出问题和拉取请求。请确保您的更改保持现有的代码风格，并包含适当的测试。 </中文翻译>