项目简介

本项目 'qiniu-mcp-server' 是一个基于 Model Context Protocol (MCP) 标准实现的服务器，旨在连接 AI 大模型客户端与七牛云服务。通过该 MCP 服务器，用户可以方便地让 AI 应用访问和操作存储在七牛云对象存储 Kodo 中的资源，以及使用 Dora 服务的相关功能（当前仓库主要聚焦于对象存储 Kodo）。

主要功能点

资源管理:
- 列举七牛云 Kodo 中配置的 Bucket 列表。
- 列举指定 Bucket 中的对象（文件）列表。
- 读取 Bucket 中对象的文本或图片内容。
工具调用:
- 提供工具让 LLM 客户端可以列举 Bucket 和对象。
- 提供工具让 LLM 客户端可以读取对象内容。
标准 MCP 协议:
- 基于 JSON-RPC 协议与客户端通信。
- 支持 Stdio 和 SSE 传输协议。

安装步骤

前置条件:
- 确保已安装 Python 3.12 或更高版本。
- 确保已安装 uv 包管理器。如果未安装，请根据仓库 README 的指引安装。

克隆仓库:

git clone [email protected]:qiniu/qiniu-mcp-server.git
cd qiniu-mcp-server

创建并激活虚拟环境:

uv venv
source .venv/bin/activate  # Linux/macOS
# 或
.venv\Scripts\activate  # Windows

安装依赖:
```
uv pip install -e .
```

服务器配置

MCP 客户端需要配置 MCP 服务器的启动命令和参数才能连接。以下是 'qiniu-mcp-server' 的 MCP 服务器配置信息，请在 MCP 客户端中进行配置：

{
  "mcpServers": {
    "qiniu": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/qiniu-mcp-server",  //  请替换为 qiniu-mcp-server 项目的绝对路径
        "run",
        "qiniu-mcp-server"
      ],
      "disabled": false
    }
  }
}

配置参数说明:

'"command"': 启动 MCP 服务器的命令，这里使用 'uv' 包管理器。
'"args"': 传递给 'uv' 命令的参数列表。
- '"--directory"': 指定项目根目录，请将 '"/path/to/qiniu-mcp-server"' 替换为实际的 'qiniu-mcp-server' 项目在您本地文件系统中的绝对路径。
- '"run"': 'uv run' 子命令用于运行 Python 模块。
- '"qiniu-mcp-server"': 指定要运行的 Python 模块名称，即 'qiniu-mcp-server'。
'"disabled"': 设置为 'false' 表示启用该 MCP 服务器。
'"server name"': 'qiniu' 是服务器名称，可以自定义。

环境变量配置:

启动服务器前，请务必配置以下环境变量。复制 '.env.example' 文件为 '.env'，并根据您的七牛云账号信息修改 '.env' 文件内容：

QINIU_ACCESS_KEY=your_access_key      #  您的七牛云 Access Key
QINIU_SECRET_KEY=your_secret_key      #  您的七牛云 Secret Key
QINIU_REGION_NAME=your_region          #  您的七牛云区域名称，例如：z0, z1, z2, na0, as0, cn-east-2
QINIU_ENDPOINT_URL=endpoint_url       #  您的七牛云 Endpoint URL，例如：https://s3.qiniucs.com (华东)
QINIU_BUCKETS=bucket1,bucket2,bucket3  #  允许访问的 Bucket 列表，多个 Bucket 用逗号分隔

基本使用方法

启动服务器: 根据您选择的传输协议启动服务器。

Stdio 模式 (默认):

uv --directory . run qiniu-mcp-server

SSE 模式 (用于 Web 应用，端口 8000):

uv --directory . run qiniu-mcp-server --transport sse --port 8000

在 MCP 客户端中使用: 配置好 MCP 客户端后，您可以通过客户端与 AI 模型进行交互，指示 AI 使用 'qiniu-mcp-server' 提供的功能。例如，在 Cline 插件中，您可以：
- 列举七牛云的资源信息 (实际会列举 Bucket 和 Object 资源)。
- 列举七牛云中所有的 Bucket。
- 列举七牛云中指定 Bucket 的文件 (Object)。
- 读取七牛云指定 Bucket 中指定文件的内容。
具体的指令取决于您使用的 MCP 客户端和 AI 模型的理解能力。您可以尝试使用自然语言指令引导 AI 调用相应的工具。例如，您可以对 AI 说： "列出我在七牛云存储中的所有 Bucket" 或 "读取我在 'my-bucket' Bucket 中 'document.txt' 文件的内容"。

您也可以使用 Model Control Protocol Inspector 进行测试和调试。

注意:

请确保配置的七牛云账号具有访问指定 Bucket 的权限。
建议限制配置的 Bucket 数量，避免资源列表过长。
详细的工具和资源定义可以参考仓库中的 'core/storage/tools.py' 和 'core/storage/resource.py' 文件。

关键词

项目简介

主要功能点

安装步骤

服务器配置

基本使用方法

信息