ugreen-nas-mcp

让 Claude（或任何 MCP 客户端）通过绿联 UGOS Pro 的「访问令牌」读写 NAS 文件。

不需要 SSH，也不用交出 NAS 账号密码：用的是 UGOS Pro 给第三方 Agent 提供的 OpenCLI 接口（HTTPS + Bearer 令牌 + protobuf），权限由令牌控制。

只有 5 个工具，没有删除、移动、Docker、应用管理等能力：

已在 UGOS Pro 1.21.0.80330 + macOS 上的 Claude 桌面版实测通过。

1. 在 NAS 上创建令牌

控制面板 → 账号设置 → 访问令牌 → 创建访问令牌：

• 业务权限只勾 文件管理（Files） 里的这 4 项：

  • 列表与属性

  • 读取与下载

  • 上传

  • 创建文件夹

• 其他应用（Docker、控制面板、应用中心等）都不要勾

• 令牌只显示一次，先复制保存好；建好后权限不能修改，缺权限只能重建

绿联的令牌不能按文件夹限权：给了 Files 权限，就能访问该账号能访问的所有文件。所以本服务提供「允许写入的目录」（UGREEN_NAS_WRITE_ROOT）把写入限制在一个目录里。也建议在 NAS 上建一个普通（非管理员）账号专门生成这个令牌。

Related MCP server: Multi-Tool MCP Server

2. 安装

方式一：Claude 桌面版扩展（推荐）

1. 从 Releases 下载 ugreen-nas.mcpb

2. 双击安装（或拖到 Claude 桌面版 设置 → 扩展）。会提示「未签名」，属于正常情况

3. 在设置页填写：

   • NAS 地址：局域网 IP（如 192.168.1.10，自动用 https://…:9443）、UGREENlink/DDNS 域名或完整 URL

   • 访问令牌

   • 允许写入的目录（建议）：如 /volume1/共享文件夹/Claude备份

   • 校验 HTTPS 证书：见下文「证书校验」

4. 启用扩展，完全退出（⌘Q）后重开 Claude

扩展使用 Claude 自带的 Node.js，电脑上不用另装 Node。

方式二：手动配置（Claude Code 或其他 MCP 客户端）

需要 Node.js 20+：

git clone https://github.com/lihaifeng01/ugreen-nas-mcp.git
cd ugreen-nas-mcp && npm install

Claude Code：

claude mcp add ugreen-nas \
  -e UGREEN_NAS_ENDPOINT=192.168.1.10 \
  -e UGREEN_NAS_TOKEN=ugpoa_v1.xxx.xxx \
  -e "UGREEN_NAS_WRITE_ROOT=/volume1/共享文件夹/Claude备份" \
  -- node /path/to/ugreen-nas-mcp/index.js

claude_desktop_config.json：

{
  "mcpServers": {
    "ugreen-nas": {
      "command": "node",
      "args": ["/path/to/ugreen-nas-mcp/index.js"],
      "env": {
        "UGREEN_NAS_ENDPOINT": "192.168.1.10",
        "UGREEN_NAS_TOKEN": "ugpoa_v1.xxxxxxxx.xxxxxxxx",
        "UGREEN_NAS_WRITE_ROOT": "/volume1/共享文件夹/Claude备份"
      }
    }
  }
}

3. 路径怎么写

• 共享文件夹：/volume1/<共享文件夹名>/...

• 个人文件夹：/home/<NAS用户名>/...

• 不能直接用 /volume1 根目录（NAS 会拒绝）

• 路径必须是绝对路径，不允许 ..

4. macOS 局域网访问（自动处理）

macOS 的「本地网络」隐私限制会拦截 Claude 桌面版启动的 MCP 进程访问局域网 IP（报 EHOSTUNREACH），而且 Claude 不出现在「本地网络」设置里，无法手动授权。

遇到这种情况，本服务会自动注册一个用户级 launchd 任务 com.ugreen-nas-mcp.forward：launchd 在 127.0.0.1:19443 监听，每个连接用系统自带的 /usr/bin/nc 转发到 NAS，然后改走本机转发并重试。

• 不需要额外软件，也不需要管理员密码

• 只监听本机回环地址；只转发原始 TCP，TLS 端到端透传，转发看不到令牌和内容

• 只在 macOS + 局域网 IP + 被拦截时启用；之后启动会直接复用

卸载：

launchctl bootout gui/$(id -u)/com.ugreen-nas-mcp.forward
rm ~/Library/LaunchAgents/com.ugreen-nas-mcp.forward.plist

5. 证书校验

• 局域网 IP：一律不校验。NAS 用自签证书，证书里也不含 IP，校验必然失败；流量仍是 HTTPS 加密的

• 域名（外网）：按「校验 HTTPS 证书」开关。走外网时建议打开，防止中间人截获令牌，前提是该域名有正规证书（UGOS 可申请 Let's Encrypt）。只有自签证书时不建议关掉校验去走外网

6. 示例：备份 Claude 记忆

把你的记忆文件全部备份到 NAS 的 /volume1/共享文件夹/Claude备份/今天日期/ 下，保持原来的目录结构

也可以让 Claude 建一个每天运行的定时任务来自动备份。

常见错误

实现说明

• 新文件用 Filesystem/CreateFile 创建：WriteFile 只能覆盖已存在的文件，对新路径会返回 1302 Path does not exist

• 追加 = 读出旧内容 → 拼接 → 整体覆盖（与服务端的 md5 一致性校验无关）

• lib/catalog.json 只保留文件相关的 6 个方法及其消息类型

开发与打包

git clone https://github.com/lihaifeng01/ugreen-nas-mcp.git
cd ugreen-nas-mcp && npm install
npm test        # 用模拟 NAS 跑端到端测试

改完代码后打包成 Claude 桌面版扩展：

1. 把 package.json 和 manifest.json 里的 version 改成同一个新版本号（如 0.2.3）

2. 运行 npm run pack：会检查版本号、安装依赖、跑测试，然后在当前目录生成 ugreen-nas.mcpb

3. 双击新的 ugreen-nas.mcpb 覆盖安装，⌘Q 退出 Claude 后重开

.mcpbignore 决定哪些文件不进安装包（README、测试、脚本等）；node_modules 会打进去，所以扩展不依赖电脑上的 Node。

发布新版本：提交并推送代码，在 GitHub 上新建 Release（标签如 v0.2.3），把 ugreen-nas.mcpb 作为附件上传。

致谢

协议分析、protobuf 编解码（lib/protobuf.js）、HTTP 客户端（lib/opencli.js，有修改）和 schema（lib/catalog.json，已裁剪）来自 dsh-ugreen-nas（MIT，© 2026 BuvkB），许可见 LICENSE.dsh-ugreen-nas。

License

MIT