Qiniu MCP Server

1# Qiniu MCP Server
2 
3## 概述
4 
5基于七牛云产品构建的 Model Context Protocol (MCP) Server，支持用户在 AI 大模型客户端的上下文中通过该 MCP
6Server 来访问七牛云存储、智能多媒体，直播服务等。
7 
8能力集：
9- 存储
10  - 获取 Bucket 列表
11  - 获取 Bucket 中的文件列表
12  - 上传本地文件，以及给出文件内容进行上传
13  - 读取文件内容
14  - 获取文件下载链接
15  - 关于访问七牛云存储详细情况请参考 [基于 MCP 使用大模型访问七牛云存储](https://developer.qiniu.com/kodo/12914/mcp-aimodel-kodo)。
16- 智能多媒体
17  - 图片缩放
18  - 图片切圆角
19- CDN
20  - 根据链接刷新文件
21  - 根据链接预取文件
22- 直播
23    - 创建直播空间bucket
24    - 创建直播流
25    - 获取直播空间列表
26    - 获取流列表
27    - 绑定推拉流域名
28    - 获取推拉流直播地址
29    - 获取直播用量
30 
31## 环境要求
32 
33- Python 3.12 或更高版本
34- uv 包管理器
35 
36如果还没有安装 uv，可以使用以下命令安装：
37```bash
38# Mac，推荐使用 brew 安装
39brew install uv
40 
41 
42# Linux & Mac
43# 1. 安装
44curl -LsSf https://astral.sh/uv/install.sh | sh
45# 2. 安装完成后，请确保将软件包安装路径（包含 uv 和 uvx 可执行文件的目录）添加到系统的 PATH 环境变量中。
46# 假设安装包路径为 /Users/xxx/.local/bin（见安装执行输出）
47### 临时生效（当前会话），在当前终端中执行以下命令：
48export PATH="/Users/xxx/.local/bin:$PATH"
49### 永久生效（推荐），在当前终端中执行以下命令：
50echo 'export PATH="/Users/xxx/.local/bin:$PATH"' >> ~/.bash_profile
51source ~/.bash_profile
52 
53 
54# Windows
55powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
56```
57 
58具体安装方式参考 [uv 安装](https://docs.astral.sh/uv/getting-started/installation/#pypi)
59 
60## 在 Cline 中使用：
61 
62步骤：
63 
641. 在 vscode 下载 Cline 插件（下载后 Cline 插件后在侧边栏会增加 Cline 的图标）
652. 配置大模型
663. 配置 qiniu MCP
67    1. 点击 Cline 图标进入 Cline 插件，选择 MCP Server 模块
68    2. 选择 installed，点击 Advanced MCP Settings 配置 MCP Server，参考下面配置信息
69   ```
70   {
71     "mcpServers": {
72       "qiniu": {
73         "command": "uvx",
74         "args": [
75           "qiniu-mcp-server"
76         ],
77         "env": {
78           "QINIU_ACCESS_KEY": "YOUR_ACCESS_KEY",
79           "QINIU_SECRET_KEY": "YOUR_SECRET_KEY",
80           "QINIU_REGION_NAME": "YOUR_REGION_NAME",
81           "QINIU_ENDPOINT_URL": "YOUR_ENDPOINT_URL",
82           "QINIU_BUCKETS": "YOUR_BUCKET_A,YOUR_BUCKET_B"
83        },
84         "disabled": false
85       }
86     }
87   }
88   ```
89 
90   ```
91   如果只使用直播功能时，支持两种鉴权模式
92   1 配置QINIU_ACCESS_KEY/QINIU_SECRET_KEY
93   {
94     "mcpServers": {
95       "qiniu": {
96         "command": "uvx",
97         "args": [
98           "qiniu-mcp-server"
99         ],
100         "env": {
101           "QINIU_ACCESS_KEY": "YOUR_ACCESS_KEY",
102           "QINIU_SECRET_KEY": "YOUR_SECRET_KEY"
103        },
104         "disabled": false
105       }
106     }
107   }
108   2 可在七牛直播控制台获取apikey后，配置QINIU_LIVE_API_KEY
109   {
110     "mcpServers": {
111       "qiniu": {
112         "command": "uvx",
113         "args": [
114           "qiniu-mcp-server"
115         ],
116         "env": {
117           "QINIU_LIVE_API_KEY": "YOUR_LIVE_API_KEY"
118        },
119         "disabled": false
120       }
121     }
122   }
123   ```
124    3. 点击 qiniu MCP Server 的链接开关进行连接
1254. 在 Cline 中创建一个聊天窗口，此时我们可以和 AI 进行交互来使用 qiniu-mcp-server ，下面给出对象存储的几个示例：
126    - 列举 qiniu 的资源信息
127    - 列举 qiniu 中所有的 Bucket
128    - 列举 qiniu 中 xxx Bucket 的文件
129    - 读取 qiniu xxx Bucket 中 yyy 的文件内容
130    - 对 qiniu xxx Bucket 中 yyy 的图片切个宽200像素的圆角
131    - 刷新下 qiniu 的这个 CDN 链接：https://developer.qiniu.com/test.txt
1325. 在 Cline 中创建一个聊天窗口，此时我们可以和 AI 进行交互来使用 qiniu-mcp-server ，下面给出直播系统的几个示例：
133    - 列举所有的直播空间
134    - 新创建1个直播空间,命名为mcptest1123
135    - 为mcptest1123新创建1个流,命名为stream1
136    - 列举一下直播空间mcptest1123中所有的流
137    - 为mcptest1123绑定推流域名 <your-push-domain>, 绑定拉流域名<your-play-domain>
138    - 获取mcptest1123下直播流stream1，对应的推流地址和拉流地址
139    - 获取最近1个小时直播的用量
140 
141注：
142cursor 中创建 MCP Server 可直接使用上述配置。
143claude 中使用时可能会遇到：Error: spawn uvx ENOENT 错误，解决方案：command 中 参数填写 uvx 的绝对路径，eg: /usr/local/bin/uvx
144 
145## 开发
1461. 克隆仓库：
147 
148```bash
149# 克隆项目并进入目录
150git clone git@github.com:qiniu/qiniu-mcp-server.git
151cd qiniu-mcp-server
152```
153 
1542. 创建并激活虚拟环境：
155 
156```bash
157uv venv
158source .venv/bin/activate  # Linux/macOS
159# 或
160.venv\Scripts\activate  # Windows
161```
162 
1633. 安装依赖：
164 
165```bash
166uv pip install -e .
167```
168 
1694. 配置
170 
171复制环境变量模板：
172```bash
173cp .env.example .env
174```
175 
176编辑 `.env` 文件，配置以下参数：
177```bash
178# S3/Kodo 认证信息
179QINIU_ACCESS_KEY=your_access_key
180QINIU_SECRET_KEY=your_secret_key
181 
182# 区域信息
183QINIU_REGION_NAME=your_region
184QINIU_ENDPOINT_URL=endpoint_url # eg:https://s3.your_region.qiniucs.com
185 
186# 配置 bucket，多个 bucket 使用逗号隔开，建议最多配置 20 个 bucket
187QINIU_BUCKETS=bucket1,bucket2,bucket3
188```
189 
190扩展功能，首先在 core 目录下新增一个业务包目录（eg: 存储 -> storage），在此业务包目录下完成功能拓展。
191在业务包目录下的 `__init__.py` 文件中定义 load 函数用于注册业务工具或者资源，最后在 `core` 目录下的 `__init__.py`
192中调用此 load 函数完成工具或资源的注册。
193 
194```shell
195core
196├── __init__.py # 各个业务工具或者资源加载
197└── storage # 存储业务目录
198    ├── __init__.py # 加载存储工具或者资源
199    ├── resource.py # 存储资源扩展
200    ├── storage.py # 存储工具类
201    └── tools.py # 存储工具扩展
202```
203 
204## 测试
205 
206### 使用 Model Control Protocol Inspector 测试
207 
208强烈推荐使用 [Model Control Protocol Inspector](https://github.com/modelcontextprotocol/inspector) 进行测试。
209 
210```shell
211# node 版本为：v22.4.0
212npx @modelcontextprotocol/inspector uv --directory . run qiniu-mcp-server
213```
214 
215### 本地启动 MCP Server 示例
216 
2171. 使用标准输入输出（stdio）模式启动（默认）：
218 
219```bash
220uv --directory . run qiniu-mcp-server
221```
222 
2232. 使用 SSE 模式启动（用于 Web 应用）：
224 
225```bash
226uv --directory . run qiniu-mcp-server --transport sse --port 8000
227```
228 
229 
230 
231 
232