在 MCP 客户端里说一句「从生产 OSS 下载 lstd/pay/a.png」,模型会自动把「生产」匹配到对应认证分组和 Bucket,然后调用下载工具。
目录
- 功能特性
- 项目结构
- 快速开始
- 认证分组配置
- MCP 工具
- 接入 MCP 客户端
- HTTP Bearer Token 认证
- 服务管理脚本
- 命令行工具
- 测试
- 发布(维护者)
- 日志与排错
- 安全建议
- 已知限制
功能特性
- 文件存在性判断:基于 OSS HEAD 请求精确判断对象是否存在,不把目录前缀误判为文件。
- 上传:支持本地文件和网络 URL,上传时可指定对象 ACL(
private/public-read/public-read-write/default)。 - 替换:用本地文件替换 OSS 上已有对象;默认保留原对象路径(URL 不变),也可按本地文件名改名并删除旧对象。
- 下载:支持单文件、多文件和整个目录;多文件与目录自动打包为 ZIP,避免大量小文件逐个落盘。
- 删除:支持单个删除和批量删除;批量删除自动去重,并按 OSS 限制每 1000 个一批提交。
- 访问地址:公共读 Bucket 可使用自定义域名直链;私有 Bucket 自动生成带有效期的签名 URL。
- 多分组认证:一个配置文件管理多套 AccessKey、Endpoint、Bucket,并通过别名做自然语言路由。
- 默认路径前缀:分组可配置
default_prefix;MCP 工具传a.png会自动补成lstd/pay/a.png,已带前缀的路径不会重复拼接。 - HTTP Bearer 认证:HTTP/SSE 模式支持 Bearer Token;监听非本机地址时强制配置,避免 OSS 能力裸奔。
- 两种接入方式:MCP 客户端本地拉起(stdio),或作为后台 HTTP 服务运行(streamable-http / SSE)。
- 跨平台托管:提供 Linux / macOS 和 Windows 的启动、停止、重启、状态、日志脚本。
- 可离线验证:冒烟测试使用假的 Bucket 客户端,不依赖真实 OSS 凭证即可运行。
项目结构
oss_mcp_server/
├── config/
│ └── oss_config.example.json # 分组配置模板(唯一可提交的配置)
├── scripts/
│ ├── mcp_service.sh # Linux / macOS 服务管理
│ ├── mcp_service.ps1 # Windows PowerShell 服务管理
│ └── mcp_service.bat # Windows 双击 / CMD 入口
├── src/
│ ├── http_auth.py # HTTP Bearer Token 中间件与启动策略
│ ├── oss_mcp_server.py # MCP 服务层:配置、分组路由、11 个工具
│ └── oss_utils.py # OSS 原子操作层 + 命令行入口
├── tests/
│ ├── smoke_http_auth.py # Bearer Token 校验与强制策略测试
│ ├── smoke_oss_utils.py # OSS 操作冒烟测试
│ ├── smoke_mcp_server.py # MCP stdio / HTTP 冒烟测试
│ ├── smoke_service_scripts.sh # 启动脚本环境准备与依赖检测测试
│ └── smoke_service_scripts.ps1 # PowerShell 启动流程编排测试
├── requirements.txt
├── pyproject.toml # PyPI 打包、依赖与 console script
├── server.json # Official MCP Registry 清单
├── README.md
└── .gitignore
分层约定:
| 目录 | 职责 |
|---|---|
config/ |
只放配置模板;真实的 oss_config.json 已被 .gitignore 排除 |
src/oss_utils.py |
封装 oss2,提供可复用的上传、下载、删除、URL、存在性判断能力 |
src/http_auth.py |
Bearer Token 中间件、Token 校验和监听地址安全策略 |
src/oss_mcp_server.py |
读取配置、解析分组别名、注册 MCP 工具并选择传输方式 |
scripts/ |
进程托管、日志、PID、端口检查,不包含业务逻辑 |
tests/ |
无真实凭证的冒烟测试,覆盖原子操作、HTTP 认证、MCP 协议链路和启动脚本环境准备 |
运行时还会自动生成 logs/、run/ 和 Python 的 __pycache__/,它们都不会进入 Git。
快速开始
1. 环境要求
- Python 3.10 及以上
- 能访问阿里云 OSS 的网络环境
- 具备目标 Bucket 读写权限的 AccessKey,或 STS 临时凭证
2. 准备运行环境
推荐直接使用服务管理脚本,start / restart 前会自动完成:
- 检测项目虚拟环境
.venv或venv; - 都不存在时,用 PATH 中的 Python 3.10+ 创建
.venv; - 升级该虚拟环境的 pip;
- 检测
oss2/mcp/uvicorn,缺失时执行pip install -r requirements.txt; - 依赖齐全后启动服务。
依赖已经齐全时不会重复执行 pip,正常启动不会额外访问网络。设置 OSS_MCP_AUTO_INSTALL=0 可关闭创建虚拟环境、升级 pip 和安装依赖;PYTHON_BIN 为严格模式,只使用指定解释器,不会修改环境。
也可以手动安装:
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
如果使用 PyCharm / IDEA 打开项目,IDE 可能会自动创建一个只有 pip 的空 venv。启动脚本会检测到缺失依赖并自动补装;若关闭了自动安装,请手动对该解释器执行 python -m pip install -r requirements.txt,否则会报 ModuleNotFoundError: No module named 'oss2' 或 'mcp'。
也可以不克隆仓库,直接从 PyPI 安装(需要 uv):
uvx oss-mcp-server --access-key-id AK --access-key-secret SK \
--endpoint oss-cn-hangzhou.aliyuncs.com --bucket demo
或者用环境变量 OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET / OSS_ENDPOINT / OSS_BUCKET 提供凭证,便于直接写进 MCP 客户端配置;多分组配置仍通过 --config 指定。
3. 准备配置
# Linux / macOS
cp config/oss_config.example.json config/oss_config.json
# Windows PowerShell
Copy-Item config\oss_config.example.json config\oss_config.json
编辑 config/oss_config.json,填入真实的 AccessKey、Endpoint、Bucket 和别名。对外提供 HTTP 服务时,还要填写 http_bearer_token 或设置 OSS_MCP_BEARER_TOKEN。真实配置文件包含凭证,不要提交到 Git。
4. 启动
本地 MCP 客户端接入(由客户端拉起进程,使用 stdio)见 接入 MCP 客户端。
直接启动 HTTP 服务:
# 仅本机访问:未配置 Token 时允许启动
python src/oss_mcp_server.py --config config/oss_config.json \
--transport streamable-http --host 127.0.0.1 --port 8000
# 对外监听:必须配置 Bearer Token
python src/oss_mcp_server.py --config config/oss_config.json \
--transport streamable-http --host 0.0.0.0 --port 8000 \
--bearer-token "<至少 16 位的随机 Token>"
后台托管:
# Linux / macOS
chmod +x scripts/mcp_service.sh
./scripts/mcp_service.sh start
# Windows
.\scripts\mcp_service.bat start
默认访问地址为 http://127.0.0.1:8000/mcp。HTTP 认证细节见 HTTP Bearer Token 认证。
认证分组配置
config/oss_config.json 使用 groups 管理多套认证信息:
{
"default_group": "prod",
"http_bearer_token": "",
"groups": {
"prod": {
"alias": "生产",
"access_key_id": "LTAI5tXXXXXXXXXXXXXX",
"access_key_secret": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"endpoint": "oss-cn-hangzhou.aliyuncs.com",
"bucket": "prod-bucket",
"domain": "https://static.example.com",
"default_prefix": "lstd/pay/",
"public_read": true
},
"test": {
"alias": "测试",
"aliases": ["测试OSS"],
"access_key_id": "LTAI5tYYYYYYYYYYYYYY",
"access_key_secret": "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYY",
"security_token": "",
"endpoint": "oss-cn-shanghai.aliyuncs.com",
"bucket": "test-bucket",
"default_prefix": "lstd/test/",
"public_read": false
}
}
}
字段说明
| 字段 | 必填 | 说明 |
|---|---|---|
default_group |
否 | 默认分组名,必须是 groups 中的键;不填时使用第一个分组 |
http_bearer_token |
对外监听时必填 | HTTP/SSE 模式的 Bearer Token,至少 16 个可打印 ASCII 字符且不能含空白;仅本机监听时可留空 |
groups |
是 | 非空对象,键为分组名称,值为该分组的配置 |
alias |
否 | 分组的主别名,便于自然语言指定,如「生产」 |
aliases |
否 | 额外别名数组,可与 alias 同时使用 |
access_key_id |
是 | 兼容 accessKeyId、accessKey |
access_key_secret |
是 | 兼容 accessKeySecret、accessSecret |
security_token |
否 | STS 临时凭证 Token,兼容 securityToken;不使用时留空或删除 |
endpoint |
是 | 如 oss-cn-hangzhou.aliyuncs.com |
bucket |
是 | 兼容 bucket_name、bucketName |
domain |
否 | 自定义访问域名;未写协议时自动补 https://,公共读时优先用于拼接 URL |
default_prefix |
否 | 对象的默认目录前缀,如 lstd/pay/;MCP 工具收到未以它开头的对象路径时自动拼接,已带前缀则不重复。兼容 defaultPrefix、prefix,默认空(不拼接) |
public_read |
否 | JSON 布尔值,兼容 publicRead;默认 false(签名 URL) |
http_bearer_token 是配置文件根节点字段,不要放进某个分组内部。public_read 等布尔字段请使用 JSON 布尔值,不要写成字符串。
config/oss_config.example.json 模板中的 default_prefix 默认为空;需要让 MCP 工具接受 a.png 这类相对路径时,填入统一目录前缀(如 lstd/pay/)。
生成一个足够随机的 Token:
python -c "import secrets; print(secrets.token_urlsafe(32))"
别名是如何匹配的
分组名称和别名都可以传给工具的 group 参数。匹配时:
- 去掉所有空白字符,并忽略大小写;
- 自动兼容常见后缀变体,例如「生产」也可以匹配「生产 OSS」「生产OSS」「生产云存储」;
- 启动时检查名称/别名冲突,若两个分组被同一个别名命中会直接报错,避免路由到错误的 Bucket;
- 不传
group时使用默认分组。
list_groups 只返回脱敏后的 AccessKey,不会返回 Secret 或 STS Token。
兼容的单分组写法
配置文件根节点直接放认证字段时,会作为一个名为 default 的分组加载:
{
"access_key_id": "LTAI...",
"access_key_secret": "...",
"endpoint": "oss-cn-hangzhou.aliyuncs.com",
"bucket": "demo-bucket"
}
MCP 服务也支持完全不用配置文件,直接传入单分组参数:
python src/oss_mcp_server.py \
--access-key-id LTAI... --access-key-secret ... \
--endpoint oss-cn-hangzhou.aliyuncs.com --bucket demo-bucket
单分组模式的分组名固定为 default。此时也可使用环境变量 OSS_ACCESS_KEY_ID、OSS_ACCESS_KEY_SECRET、OSS_SECURITY_TOKEN、OSS_ENDPOINT、OSS_BUCKET、OSS_DOMAIN、OSS_DEFAULT_PREFIX、OSS_PUBLIC_READ。
MCP 工具
服务共暴露 11 个工具。除 list_groups 外,其余工具都接受可选的 group 参数,传分组名称或别名均可。
| 工具 | 功能 | 主要参数 | 属性 |
|---|---|---|---|
list_groups |
列出分组、别名、Bucket、默认前缀,凭证脱敏 | 无 | 只读 |
file_exists |
精确判断对象是否存在 | object_name、group |
只读 |
upload_file |
上传本地文件 | local_path、object_name、acl、group |
写 |
upload_from_url |
下载网络文件并上传 | url、object_name、acl、group |
写、联网 |
replace_file |
用本地文件替换已有对象,可保留原名或按本地文件名改名 | local_path、object_name、keep_original_name、acl、group |
写、可能删除旧对象 |
download_file |
下载单个对象到本地 | object_name、local_path、group |
写本地 |
download_files |
下载多个对象并打包 ZIP,保留完整对象路径 | object_names、local_dir、zip_name、group |
写本地 |
download_folder |
按前缀下载整个目录并打包 ZIP,保留相对路径 | prefix、local_dir、zip_name、group |
写本地 |
delete_file |
删除单个对象 | object_name、group |
删除,不可恢复 |
delete_files |
批量删除对象,自动分批 | object_names、group |
删除,不可恢复 |
get_file_url |
生成公共读直链或私有签名 URL | relative_path、prefix、expires、public、group |
只读 |
参数补充
- 对象路径与
default_prefix:object_name、object_names、下载的prefix以及relative_path都支持相对路径。未以分组default_prefix开头时自动补齐,已带前缀时保持不变;前导/会被去掉。例如分组前缀为lstd/pay/时,a.png和lstd/pay/a.png指向同一个对象,批量列表会先归一化再去重。 acl:可选default、private、public-read、public-read-write。不传时继承 Bucket 的 ACL。keep_original_name:仅replace_file使用。默认true,表示覆盖原对象内容、对象路径和 URL 不变;设为false时使用本地文件名放到原对象所在目录,上传成功后删除旧对象。local_path:可以是文件路径,也可以是已存在的目录;传入目录时保留 OSS 文件名。不传时保存到当前工作目录。local_dir:ZIP 的存放目录,默认当前工作目录。zip_name:ZIP 文件名或路径。不传时自动生成,例如prod-bucket_download_20261029_153000.zip。prefix(下载):未以/结尾时会自动补齐;空目录会报错,并把已创建的空 ZIP 删除。prefix(获取 URL):不传时使用分组的default_prefix;传入已经带完整前缀的路径也不会重复拼接。expires:私有签名 URL 的有效期,单位秒,默认 3600。public:不传时使用分组的public_read。
工具返回值会带上实际命中的分组信息,便于确认路由是否正确:
{
"group": "prod",
"group_alias": "生产",
"bucket": "prod-bucket",
"object_name": "lstd/pay/a.png",
"exists": true
}
下载类工具返回本地绝对路径和大小;批量删除返回实际删除的对象列表。replace_file 返回 old_object_name、new_object_name、renamed、old_deleted,便于确认是否改名以及旧对象是否已删除。返回值中的 object_name、deleted、prefix、file_count 都基于补全默认前缀后的完整路径计算。delete_file、delete_files 与 replace_file 带有 destructive 注解,支持该能力的客户端通常会请求二次确认。
替换规则
- 原对象必须存在;不存在会拒绝执行,避免对象路径写错时静默变成新建。
- 保留原名:直接
PutObject覆盖原对象内容,对象 ACL 由acl参数决定,不传则继承 Bucket。 - 改名:新对象路径为“原对象所在目录 + 本地文件名”;如果该路径已存在其他对象,直接报错,不覆盖第三方文件。
- 执行顺序是先上传新内容,成功后再删除旧对象。删除失败会保留两个对象并明确报错,不会假装成功。
- 单次覆盖在 OSS 层是原子的;改名模式包含“上传 + 删除”两步,不是跨对象原子操作,建议开启 Bucket 版本控制。
接入 MCP 客户端
方式一:stdio(推荐本地使用)
由 MCP 客户端拉起 Python 进程,不需要常驻端口。通用 mcpServers 配置如下(不同客户端字段可能略有差异):
{
"mcpServers": {
"oss": {
"command": "python",
"args": [
"<项目绝对路径>/src/oss_mcp_server.py",
"--config",
"<项目绝对路径>/config/oss_config.json"
]
}
}
}
建议把 command 换成项目虚拟环境中的 Python 绝对路径,确保客户端能加载 mcp、oss2 和 requests:
- Linux / macOS:
<项目绝对路径>/.venv/bin/python - Windows:
<项目绝对路径>/.venv/Scripts/python.exe
--config 也可以省略,此时服务会读取项目下的 config/oss_config.json。stdio 模式下不要手动启动服务,客户端会自行管理进程。
如果使用 PyPI 包,把 command 换成 uvx、args 换成包名,凭证通过 env 传入:
{
"mcpServers": {
"oss": {
"command": "uvx",
"args": ["oss-mcp-server"],
"env": {
"OSS_ACCESS_KEY_ID": "LTAI...",
"OSS_ACCESS_KEY_SECRET": "...",
"OSS_ENDPOINT": "oss-cn-hangzhou.aliyuncs.com",
"OSS_BUCKET": "demo"
}
}
}
}
多分组仍可在 args 中追加 --config 指向分组配置文件。
方式二:streamable-http
先启动服务。本机未配置 Token 时可直接访问;启用认证后,客户端必须带 Authorization 请求头:
# 本机免 Token(默认)
python src/oss_mcp_server.py --config config/oss_config.json \
--transport streamable-http --host 127.0.0.1 --port 8000
# 启用 Bearer Token
python src/oss_mcp_server.py --config config/oss_config.json \
--transport streamable-http --host 127.0.0.1 --port 8000 \
--bearer-token "$OSS_MCP_BEARER_TOKEN"
MCP 端点为:
http://127.0.0.1:8000/mcp
支持 URL 和自定义请求头的客户端可以这样配置:
{
"mcpServers": {
"oss-http": {
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer <TOKEN>"
}
}
}
}
如果客户端不支持自定义请求头,就无法连接已启用 Bearer 认证的 HTTP 服务,请改用 stdio,或通过支持注入请求头的反向代理/客户端插件接入。若客户端要求显式指定传输类型,请按其文档补充 streamable-http 类型字段。
方式三:SSE(兼容旧客户端)
python src/oss_mcp_server.py --config config/oss_config.json \
--transport sse --host 127.0.0.1 --port 8000 \
--bearer-token "$OSS_MCP_BEARER_TOKEN"
端点为 http://127.0.0.1:8000/sse,同样需要通过 Authorization: Bearer <TOKEN> 请求头认证。新客户端优先使用 streamable-http。
自然语言路由示例
配置了 prod(别名「生产」)和 test(别名「测试」)后:
| 用户说法 | 模型应传入的参数 |
|---|---|
从生产 OSS 下载 lstd/pay/a.png |
group="生产" |
看看测试 OSS 上有没有 lstd/test/b.png |
group="测试" |
上传到 OSS 的 lstd/pay/c.png |
不传 group,使用默认分组 |
上传 c.png 到生产 OSS |
group="生产"、object_name="c.png",自动补成 lstd/pay/c.png |
服务初始化信息中会列出所有分组和别名,工具的 group 参数描述也会动态写入别名列表,模型不需要猜测。
HTTP Bearer Token 认证
Bearer Token 只作用于 HTTP/SSE 传输,stdio 由本地客户端直接拉起进程,不经过网络。启用后,/mcp、/sse 及后续会话请求都必须携带:
Authorization: Bearer <TOKEN>
Token 来源与优先级
| 优先级 | 来源 | 示例 |
|---|---|---|
| 1 | 命令行参数 | --bearer-token "<TOKEN>" |
| 2 | 环境变量 | OSS_MCP_BEARER_TOKEN="<TOKEN>" |
| 3 | 配置文件根节点 | "http_bearer_token": "<TOKEN>" |
推荐把 Token 放入环境变量或已被 .gitignore 排除的 config/oss_config.json,不要写进脚本、README 或提交记录。命令行参数可能出现在进程列表中,生产环境优先使用环境变量或配置文件。Token 至少 16 个字符,只能包含可打印 ASCII 字符(不能使用中文等非 ASCII 字符),不能包含空白字符;日志只记录“认证已启用”,不会输出 Token。
强制策略
| 监听地址 | 是否配置 Token | 行为 |
|---|---|---|
127.0.0.1 / localhost / ::1 |
否 | 警告后允许启动,方便本地开发 |
| 本机地址 | 是 | 所有 HTTP 请求校验 Token |
0.0.0.0 / 局域网 IP / 公网 IP |
否 | 拒绝启动并提示配置 Token |
| 非本机地址 | 是 | 允许启动,所有 HTTP 请求校验 Token |
服务没有 TLS。对外监听时应放在反向代理之后,由代理提供 HTTPS,并限制来源 IP;Bearer Token 只解决“调用方是否持有令牌”,不能替代网络边界和 TLS。
验证认证是否生效
# 未携带 Token:应返回 401
curl -i http://127.0.0.1:8000/mcp
# 携带 Token:认证通过后返回 MCP 协议层的响应
curl -i -H "Authorization: Bearer $OSS_MCP_BEARER_TOKEN" \
http://127.0.0.1:8000/mcp
未认证响应示例:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="oss-mcp"
Content-Type: application/json; charset=utf-8
{"error":"unauthorized","message":"Missing or invalid Bearer token"}
如果普通 GET 在认证通过后返回 406 Not Acceptable,说明已经通过 Token 校验,只是请求不符合 MCP 会话握手要求;用 MCP 客户端初始化会话即可。
常见配置示例
Linux / macOS 环境变量:
export OSS_MCP_BEARER_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
./scripts/mcp_service.sh restart
Windows PowerShell:
$env:OSS_MCP_BEARER_TOKEN = "请替换为至少16位的随机Token"
.\scripts\mcp_service.ps1 restart
配置文件方式:
{
"default_group": "prod",
"http_bearer_token": "请替换为至少16位的随机Token",
"groups": {
"prod": {
"access_key_id": "LTAI...",
"access_key_secret": "...",
"endpoint": "oss-cn-hangzhou.aliyuncs.com",
"bucket": "prod-bucket"
}
}
}
客户端配置中的请求头:
"headers": {
"Authorization": "Bearer 请替换为实际Token"
}
服务管理脚本
命令一览
两个平台的脚本行为一致:
| 命令 | 作用 |
|---|---|
start |
后台启动服务;已在运行则直接返回,不重复启动 |
stop |
根据 PID 文件停止服务 |
restart |
先停止再启动 |
status |
查看运行状态、PID、配置、监听地址和日志位置 |
logs |
实时跟踪日志,按 Ctrl+C 退出 |
Linux / macOS
chmod +x scripts/mcp_service.sh
./scripts/mcp_service.sh start
./scripts/mcp_service.sh status
./scripts/mcp_service.sh logs
./scripts/mcp_service.sh restart
./scripts/mcp_service.sh stop
脚本使用 nohup 在后台运行,默认:
- 配置文件:
config/oss_config.json - 监听地址:
127.0.0.1:8000 - 传输方式:
streamable-http - 端点:
/mcp
start / restart 前会按以下顺序准备运行环境,并逐个验证是否为 Python 3.10+ 且能导入 oss2 / mcp / uvicorn:
PYTHON_BIN:严格模式,必须可用,不会自动创建环境、升级 pip 或安装依赖,也不会回退;- 项目虚拟环境:Windows 为
.venv\Scripts\python.exe、venv\Scripts\python.exe,其他系统为.venv/bin/python、venv/bin/python; - 找不到可用项目虚拟环境时,若允许自动安装,用 PATH 中的 Python 创建
.venv(Windows 优先python,避免应用商店的python3占位程序); - 虚拟环境缺依赖时,先执行
pip install --upgrade pip,再执行pip install -r requirements.txt,然后重试; - 项目虚拟环境仍不可用时,回退到 PATH 中依赖齐全的 Python。
健康环境会直接使用,不会重复升级 pip 或安装依赖;pip 升级失败时只提示并继续安装依赖,不会直接中断启动。设置 OSS_MCP_AUTO_INSTALL=0 可关闭自动创建 .venv、升级 pip 和安装依赖。环境准备完成后会检查服务脚本、配置文件和端口占用,并最多等待 20 秒确认端口就绪。
Windows
双击或在 CMD 中执行:
scripts\mcp_service.bat start
scripts\mcp_service.bat stop
scripts\mcp_service.bat restart
scripts\mcp_service.bat status
scripts\mcp_service.bat logs
直接双击 .bat 时默认执行 start,结束后会暂停窗口以便查看结果。
也可以直接调用 PowerShell 脚本:
powershell -ExecutionPolicy Bypass -File .\scripts\mcp_service.ps1 start
powershell -ExecutionPolicy Bypass -File .\scripts\mcp_service.ps1 status
Windows 脚本使用隐藏窗口的 Start-Process 托管进程,并设置 PYTHONIOENCODING=utf-8 避免日志乱码。每次启动会把旧的 mcp.log、mcp.out.log 轮转为 .prev,避免日志无限增长。虚拟环境创建、pip 升级和依赖安装流程与 Linux 脚本一致,新建的虚拟环境同样位于项目根目录的 .venv。
环境变量
| 变量 | 默认值 | 说明 |
|---|---|---|
PYTHON_BIN |
自动探测 | 严格指定 Python 解释器(绝对路径或命令名,如 python);必须为 3.10+ 且已安装依赖,否则直接报错,不会创建虚拟环境或安装依赖 |
OSS_MCP_AUTO_INSTALL |
1 |
自动创建 .venv、升级 pip 并安装 requirements.txt;设为 0 时只使用现有可用环境,不创建、不升级、不安装 |
OSS_MCP_CONFIG |
config/oss_config.json |
配置文件路径 |
OSS_MCP_HOST |
127.0.0.1 |
监听地址 |
OSS_MCP_PORT |
8000 |
监听端口 |
OSS_MCP_TRANSPORT |
streamable-http |
streamable-http 或 sse |
OSS_MCP_BEARER_TOKEN |
无 | HTTP/SSE 的 Bearer Token;监听非本机地址时必填,会继承给服务进程 |
示例:
OSS_MCP_PORT=8010 ./scripts/mcp_service.sh restart
$env:OSS_MCP_PORT = "8010"
.\scripts\mcp_service.ps1 restart
修改
OSS_MCP_HOST前请阅读HTTP Bearer Token 认证和安全建议。监听非本机地址必须配置 Token,且应放在 TLS 反向代理之后。
运行时文件
| 路径 | 说明 |
|---|---|
logs/mcp.log |
Linux:stdout + stderr;Windows:stderr / 应用日志 |
logs/mcp.out.log |
Windows:stdout |
logs/*.prev |
Windows:上一次启动的日志备份 |
run/mcp.pid |
当前服务进程 PID |
这些路径都已加入 .gitignore。
命令行工具
src/oss_utils.py 可以脱离 MCP 单独使用,适合脚本、定时任务和临时排查。认证参数是全局参数,必须放在子命令之前。命令行工具不读取分组配置,default_prefix 只作用于 MCP 分组;CLI 请直接传入完整对象路径(或显式使用 url --prefix)。
认证参数
| 参数 | 环境变量 | 说明 |
|---|---|---|
--access-key-id |
OSS_ACCESS_KEY_ID |
AccessKey ID |
--access-key-secret |
OSS_ACCESS_KEY_SECRET |
AccessKey Secret |
--security-token |
OSS_SECURITY_TOKEN |
STS Token(可选) |
--endpoint |
OSS_ENDPOINT |
如 oss-cn-hangzhou.aliyuncs.com |
--bucket |
OSS_BUCKET |
Bucket 名称 |
子命令
| 子命令 | 用途 | 关键选项 |
|---|---|---|
upload |
上传本地文件或网络文件 | --file / --url、--key、--acl |
replace |
用本地文件替换已有对象 | --file、--key、--use-local-name、--acl |
download |
下载单文件、多文件或目录 | --key(可重复)、--prefix、-o、-d、--zip-name |
delete |
删除一个或多个文件 | --key(可重复) |
url |
生成访问地址 | --path、--prefix、--expires、--public |
常用示例
# 上传本地文件并设为公共读
python src/oss_utils.py \
--access-key-id LTAI... --access-key-secret ... \
--endpoint oss-cn-hangzhou.aliyuncs.com --bucket demo-bucket \
upload --file ./a.png --key lstd/pay/a.png --acl public-read
# 从 URL 上传
python src/oss_utils.py <认证参数> \
upload --url https://example.com/logo.png --key lstd/pay/logo.png
# 替换已有文件,保留原对象路径(URL 不变)
python src/oss_utils.py <认证参数> \
replace --file ./new-logo.png --key lstd/pay/logo.png
# 替换并按本地文件名改名,成功后删除旧对象
python src/oss_utils.py <认证参数> \
replace --file ./new-logo.png --key lstd/pay/logo.png --use-local-name
# 下载单个文件到目录
python src/oss_utils.py <认证参数> \
download --key lstd/pay/a.png -o ./downloads/
# 下载多个文件并打包
python src/oss_utils.py <认证参数> \
download --key lstd/pay/a.png --key lstd/pay/b.png \
-d ./downloads --zip-name batch.zip
# 下载整个目录(自动打包,ZIP 内保留相对路径)
python src/oss_utils.py <认证参数> \
download --prefix lstd/pay/2026/ -d ./downloads
# 批量删除
python src/oss_utils.py <认证参数> \
delete --key lstd/pay/a.png --key lstd/pay/b.png
# 获取私有签名 URL
python src/oss_utils.py <认证参数> \
url --path a.png --prefix lstd/pay/ --expires 600
下载行为
- 单文件、没有传
--zip-name、且对象路径不以/结尾:直接下载为本地文件。 - 传了多个
--key、使用--prefix,或对象路径以/结尾:打包为 ZIP。 - 单文件传了
--zip-name:也会打包为 ZIP。 - 多文件 ZIP 内保留完整 OSS 对象路径,避免不同目录下的同名文件互相覆盖。
- 目录 ZIP 内保留相对目录前缀的路径,例如
lstd/pay/2026/01/a.txt会变成01/a.txt。 - 批量删除会自动去重,并每 1000 个对象提交一次。
replace默认保留原对象路径;--use-local-name使用本地文件名并删除旧对象。原对象不存在或改名目标已存在时返回1。- 命令成功返回码为
0,OSS 或网络异常返回1,参数错误由 argparse 返回非零退出码。
测试
在项目根目录执行:
python tests/smoke_http_auth.py
python tests/smoke_oss_utils.py
python tests/smoke_mcp_server.py
bash tests/smoke_service_scripts.sh
测试覆盖:
- Bearer Token 缺失/错误返回 401,正确 Token 可完成 MCP 会话;
- Token 强度、来源优先级、本机免 Token 和非本机强制 Token 策略;
- 认证日志不会泄露 Token;
- 启动脚本的 Windows / POSIX 虚拟环境路径识别、自动创建
.venv、pip 升级与依赖安装顺序、健康环境跳过 pip、PYTHON_BIN严格模式、缺依赖回退,以及 PowerShell / Bash 流程一致性; - 本地上传、URL 上传、ACL 请求头、非法 ACL 拒绝;
- 替换文件:保留原名、按本地文件名改名、原对象不存在、改名目标重名、删除旧对象失败;
- 单文件下载、多文件 ZIP、目录 ZIP、空目录报错;
- 对象存在性判断(存在 / 不存在 / 空路径);
- 分组别名路由、默认分组、未知分组报错;
- 默认前缀归一化:相对路径自动补齐、已带前缀不重复、批量列表归一化去重、目录与 URL 拼接一致;
- 批量删除去重与 1000 个一批的分片;
- 公共读直链与私有签名 URL;
- MCP stdio 与 streamable-http 两种传输方式,HTTP 端口动态分配;
- 命令行上传、替换、下载、删除、URL 生成和缺少认证参数的情况。
测试使用内置的假 Bucket 和临时配置,不需要真实 AccessKey,也不会访问真实 OSS。真实环境的权限、网络、签名和 Bucket 策略仍建议上线前用测试 Bucket 联调一次。
发布(维护者)
项目按 PyPI 包 oss-mcp-server 打包,并在根目录提供 Official MCP Registry 清单 server.json。
# 构建并发布到 PyPI
uv build
uv publish
# 发布到 Official MCP Registry;版本号需与 pyproject.toml、server.json 一致
mcp-publisher login github
mcp-publisher validate
mcp-publisher publish
PulseMCP 当前暂停自助提交,恢复后会从 Official MCP Registry 自动抓取;Smithery 的托管与自助发布入口已关闭,不再需要 smithery.yaml。
日志与排错
| 现象 | 处理方式 |
|---|---|
未找到配置文件 |
复制模板:cp config/oss_config.example.json config/oss_config.json,Windows 使用 Copy-Item |
ModuleNotFoundError: No module named 'oss2' / 'mcp' |
IDE 选中的虚拟环境没有安装依赖;直接使用启动脚本(会检测并安装到项目 venv),或对同一个解释器执行 python -m pip install -r requirements.txt |
当前 Python 缺少依赖 / 未找到依赖齐全的 Python |
脚本已尝试创建 .venv、升级 pip 并安装 requirements.txt,也检查了 PATH;请确认能访问 PyPI,或按提示手动安装后用 PYTHON_BIN 指定解释器 |
脚本选中了应用商店的 python3 |
在 Windows 上优先使用 python;也可用 PYTHON_BIN 指向项目 venv\Scripts\python.exe |
端口 8000 已被其他进程占用 |
停止占用进程,或设置 OSS_MCP_PORT=8010 后重启 |
| 启动后端口 20 秒未就绪 | 执行 scripts/mcp_service.sh logs(Windows 使用 .bat logs)查看异常 |
| PowerShell 提示禁止运行脚本 | 使用 powershell -ExecutionPolicy Bypass -File .\scripts\mcp_service.ps1 start |
| MCP 客户端看不到工具 | 检查客户端配置中的脚本路径、Python 路径和配置文件路径是否为绝对路径;确认依赖安装在同一 Python 环境 |
| HTTP 客户端连接失败 | 确认服务监听地址、端口和端点 /mcp;远程访问时检查防火墙和 Host 校验设置 |
HTTP 返回 401 Unauthorized |
客户端没有携带或携带了错误的 Authorization: Bearer <TOKEN>;检查 Token 来源优先级和客户端请求头 |
| 监听非本机地址启动失败 | 未配置 Bearer Token;设置 --bearer-token、OSS_MCP_BEARER_TOKEN 或配置 http_bearer_token |
Token 长度至少为 16 个字符 / 不能包含空白字符 / 只能包含可打印的 ASCII 字符 |
重新生成合规 Token:python -c "import secrets; print(secrets.token_urlsafe(32))" |
| 修改 Token 后客户端仍 401 | 重启服务并更新客户端请求头;环境变量优先级高于配置文件 |
AccessDenied / NoSuchBucket |
检查 AccessKey 权限、Bucket 名称、Endpoint 区域是否匹配 |
未知的认证分组或别名 |
调用 list_groups 查看实际名称;检查多个分组是否存在别名冲突 |
| Windows 日志中文乱码 | 使用脚本启动(已设置 UTF-8);直接运行时设置 PYTHONIOENCODING=utf-8 |
安全建议
- 不要提交真实配置:只提交
config/oss_config.example.json;config/oss_config.json已被.gitignore排除,其中可能同时包含 AccessKey 和 Bearer Token。 - 最小权限:为 MCP 单独创建 RAM 用户或 STS 临时凭证,只授予需要的 Bucket / 前缀权限,避免使用主账号 AccessKey。
- 谨慎开放删除能力:
delete_file、delete_files不可恢复;replace_file在改名模式下也会删除旧对象,并可能覆盖原对象内容。建议开启 Bucket 版本控制或定期备份,并在客户端启用人工确认。 - HTTP 服务优先只监听本机:
127.0.0.1不会暴露到局域网。监听非本机地址时服务强制要求 Bearer Token,但仍应通过反向代理增加 TLS、来源限制和访问日志。 - 妥善保管 Bearer Token:使用至少 16 位可打印 ASCII 的随机值,优先放在环境变量或已被忽略的配置文件中;怀疑泄露时立即轮换 Token 并重启服务。
- 令牌不是用户体系:当前 Bearer Token 是所有客户端共享的静态令牌,只表示“持有令牌”,不提供用户身份、权限分级或审计归属。
- 避免公共读写:除非确有需要,不要使用
public-read-write;公共读文件应确认不包含敏感信息。 - 及时轮换凭证:一旦发现泄露,立即在阿里云控制台禁用并轮换 AccessKey。
- 保护日志:日志可能包含对象路径和错误详情,分享前先检查并脱敏;服务不会主动记录 Bearer Token。
已知限制
- 目录下载当前按对象顺序串行下载,超大目录耗时取决于网络和对象数量。
- URL 上传会先把远程内容读入内存,超大文件建议先落盘再使用
upload_file。 - 不提供断点续传、分片上传进度展示或下载限速。
replace_file改名模式由“上传新对象 + 删除旧对象”两步完成,不是跨对象原子操作;删除失败时新旧对象会同时存在,并返回明确错误。replace_file不传acl时,新对象继承 Bucket ACL,不会自动沿用被替换对象的 ACL;替换公共读文件时请显式传acl=public-read。- HTTP 模式使用单个静态 Bearer Token,不区分用户、不提供按工具授权、用量限流或 Token 自动轮换。
- 启动脚本自动创建虚拟环境和安装依赖需要可访问 PyPI;Debian / Ubuntu 的系统 Python 还需要
python3-venv(sudo apt install python3-venv)。离线环境请先手动安装requirements.txt,或设置OSS_MCP_AUTO_INSTALL=0后自行管理环境。 file_exists只做精确对象匹配;判断“目录是否存在”需要按前缀列出对象,本工具不提供该语义。- 冒烟测试使用假 Bucket,不能替代真实 OSS 的权限和网络联调。
Metadata
Release files for oss-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oss_mcp_server-0.1.0.tar.gz | 54.8 kB | Without provenance | Details for oss_mcp_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oss_mcp_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for oss_mcp_server-0.1.0-py3-none-any.whl |
Total release size: 87.1 kB
Release files / oss_mcp_server-0.1.0.tar.gz
| Download URL | oss_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 54.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
442853eb6906bd759ab401c2bb8e4c21eaf0d21daadae674632c1a21d49b95ea
|
|
BLAKE2b-256 checksum How to use checksums |
d39d3cee03b215f30f5eb990d7b44502f8a6245d02cdce64c0f372431965befc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / oss_mcp_server-0.1.0-py3-none-any.whl
| Download URL | oss_mcp_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 32.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8683177f3f34b6304395cc1c81ff129e22cf95c0b0d4b821ce67049695595ef
|
|
BLAKE2b-256 checksum How to use checksums |
5d5c4c784e9e85c8913345627b0628594d81f7ee7b6f0c8338b1258cef606b5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.9 {"installer":{"name":"uv","version":"0.12.9","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for oss-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.