S3 MCP Server

🚀 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     # 項目配置和依賴關係

🚀 開發與部署

開發步驟

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

部署步驟

1. 創建新版本標籤：

npm version patch

2. 推送到 npm 註冊表：

npm publish --access public

GitHub Actions 工作流會在推送新的版本標籤時自動發佈包。

📄 許可證

本項目採用 MIT 許可證。

💪 貢獻

如需貢獻，請參考項目倉庫中的貢獻指南。