ossuno-mcp · npm

两行命令，
AI 接管你的 OSS。

ossuno-mcp 是可独立使用的 MCP（Model Context Protocol）服务器。注册之后，对你的 AI 助手说一句话，就能浏览 Bucket、上传下载文件、生成临时下载链接。

npx 会自动安装与你的 Mac 架构匹配的预编译二进制。

$ npx ossuno-mcp auth
# 一次性配置 AccessKey — 只存进 macOS 钥匙串

$ npx ossuno-mcp install
# 检测到 Codex · Claude Desktop · Cursor · Trae — 已注册 ✓

需要 macOS 与 Node ≥ 18 凭证不经过 AI 客户端在 npm 查看没有 Node？从源码构建

工作原理

AI + ossuno-mcp
就是你的 OSS 助手。

MCP 是 AI 客户端与外部工具之间的开放协议。ossuno-mcp 把你的阿里云 OSS 变成 AI 的标准工具集：AI 发起指令，ossuno-mcp 用钥匙串里的凭证调用 OSS，再把结果交回给 AI。

你正在用的 AI 客户端 Codex · Claude Desktop · Claude Code · Cursor · Trae · Windsurf

钥匙串凭证 · 本机运行 ossuno-mcp 浏览 · 上传 · 下载 · 签名链接 · OSS 专家提示词

你的数据 阿里云 OSS Bucket · 对象 · RAM 权限，一切保持原样

说一句话

剩下的，交给 AI。

「列出 ossuno-assets 里所有超过 100 MB 的视频。」

list_bucketslist_objects

分页扫遍整个 Bucket，按类型、大小、时间筛选，再报给你。

「把桌面的 hero.png 传到 assets/2026/，再给我一个 24 小时有效的链接。」

upload_filepresign_url

上传完成即返回对象 URL；私有 Bucket 自动生成带签名的临时链接。

「把这个月导出的报表，都下载到 ~/Documents/Reports。」

list_objectsdownload_file

本地已有同名文件时不覆盖，报错提示换路径，与 App 行为一致。

提供的能力

五个工具，两个提示词。

工具	说明
list_buckets	列出账号下所有 Bucket（名称、地域、创建时间）
list_objects	按文件夹层级浏览对象；用 `continuation_token` 逐页列完，不遗漏后续对象
upload_file	上传允许目录内的普通文件；默认拒绝覆盖，明确确认后才可传 `overwrite=true`
download_file	下载到允许目录；拒绝符号链接逃逸，本地已有同名文件时不覆盖
presign_url	为私有 Bucket 的对象生成带签名的临时下载链接（默认 1 小时）

除工具外，服务器还内置 2 个提示词，可在客户端的 Prompts 面板一键使用：

提示词	说明
ossuno-oss-expert	把 Agent 定位为 OSS 操作专家：先浏览再操作、删除前确认、私有桶自动给临时链接
oss-batch-upload	批量上传工作流：确认目录 → 展示清单 → 逐个上传保留目录结构 → 汇总报告

连接建立时，服务器还会下发 Agent 使用说明（instructions），支持的客户端会直接展示，用于约束 AI 行为。

支持的客户端

主流客户端，
自动检测注册。

以下客户端可由 npx ossuno-mcp install 自动检测并注册：

Codex
Claude Desktop
Claude Code
Cursor
Trae
Windsurf

其他支持 stdio 传输的客户端（VS Code Copilot、Cline、Qoder 等）可手动配置：

{
  "mcpServers": {
    "ossuno": {
      "command": "npx",
      "args": ["-y", "ossuno-mcp"],
      "env": { "OSSUNO_MCP_DEFAULT_BUCKET": "my-bucket" }
    }
  }
}

env 里的 OSSUNO_MCP_DEFAULT_BUCKET（可选）设置默认 Bucket：设置后 bucket 参数对 AI 变为可选，桶名会直接出现在工具描述中，任何 AI 客户端都能看到；AI 仍可显式指定其他 Bucket。

各客户端的配置文件位置与差异见 GitHub 上的完整 MCP 文档。JSON 配置合并写入并保留 .bak 备份，不影响其他 MCP 服务器。

进阶用法

按需，再多走一步。

准备 Node

需要 macOS 与 Node ≥ 18。终端里检查版本，没有的话用 Homebrew 一行装好。

$ node -v
# 没有输出 v18+ 就执行：
$ brew install node

多账号管理

支持多个配置档案：列出、切换、删除、验证，适合同时管理多套凭证。

$ npx ossuno-mcp auth --list
# --use <名称> 切换 / --remove 删除
$ npx ossuno-mcp auth --test

卸载与源码构建

移除注册一行命令。没有 Node 时，也可以克隆仓库用 Swift 构建（在 Terminal.app 中执行）。

$ npx ossuno-mcp uninstall
# 源码构建：
$ git clone https://github.com/ihopefulChina/Ossuno
$ cd Tools/ossuno-mcp && swift build -c release

安全边界

放心的前提，
是边界清晰。

凭证隔离

AccessKey Secret 与 STS Token 只存 macOS 钥匙串，AI 客户端接触不到凭证本身，与 Ossuno App 账号相互独立。

最小权限

建议使用只授予目标 Bucket 必要动作的 RAM 子账号。默认安全上传需要 oss:GetBucketVersioning、oss:GetObject 与 oss:PutObject，缺少检查权限时会安全拒绝。

先确认，再执行

上传默认拒绝远端同名对象；只有你明确确认替换后，AI 才能传 overwrite=true。

本地范围明确

默认只访问桌面、文稿、下载和临时目录；可用 OSSUNO_MCP_ALLOWED_ROOTS 精确增加目录，符号链接不能越界。

常见问题

遇到问题，
先看这里。

AI 提示「找不到配置档案」	先运行 `npx ossuno-mcp auth` 完成凭证配置
连接失败	确认配置里 command 为 `npx`、args 包含 `-y ossuno-mcp`；从源码运行时，检查二进制绝对路径与执行权限
弹出钥匙串授权窗口	重新编译后二进制签名变化所致，属正常现象，点一次「始终允许」即可
上传报签名错误	运行 `npx ossuno-mcp auth --test` 验证凭证与地域是否匹配
本地路径被拒绝	使用桌面、文稿或下载目录，或配置 `OSSUNO_MCP_ALLOWED_ROOTS` 后重启客户端
想换账号	`npx ossuno-mcp auth --use <名称>` 切换活动档案后重启 AI 客户端
移除注册	`npx ossuno-mcp uninstall`，或加 `--client` 指定客户端

现在，
让 AI 试一下。

完整 MCP 文档问题反馈

两行命令，AI 接管你的 OSS。

AI + ossuno-mcp 就是你的 OSS 助手。