ZSpace NAS MCP

90 个 MCP tool + 6 个 skill,让 Claude/Cursor 直接操作极空间 NAS。

你只需要其中一部分

这个仓库包含 3 个独立组件,按需取用。不需要 clone 全部:

你是	你需要	不需要
MCP 用户(想让 Claude Code 操作 NAS)	`zspace/mcp_server/` + `nas/` + `.env`(API 内置在 MCP 里)	Skill / Dashboard / RAG
Skill 用户(想用自动化工作流)	复制 `skills/<name>/` 到自己项目	MCP 源码 / Dashboard / RAG
RAG 用户(想要语义搜索)	`rag-server/` docker compose	Skill / Dashboard
开发者(想加新 tool/skill)	clone 整个仓库	—

MCP 用户(3 步装上)

# 1. 安装 Python 包
git clone <repo> && cd zspace-mcp-poc
pip install -e .                    # 或用 ./start.sh deps

# 2. 配置连接
cp zspace/.env.example .env && vi .env     # 填 NAS_HOST/USER/PASSWORD

# 3. 接入 Claude Code
./start.sh mcp-cfg                  # 打印配置 → 粘到 mcp.json
# 重启 Claude Code,90 tool 自动出现

首次验证: python skills/nas-setup/scripts/check.py

Skill 用户(复制到你的项目)

# 把需要的 skill 复制到你的 Claude Code 项目
cp -r skills/nas-setup ~/your-project/skills/
# 前提: 你的项目也已配置 MCP(上一步)

skill 在 skills/ 目录下,Claude Code 在该目录启动时自动发现。当前 6 个 skill: nas-setup(前置) rag-manager(RAG管理) media-organizer ios-memo-bak label-manager file-organizer

RAG 用户(Docker 部署到 NAS)

cd rag-server
docker compose up -d                # image: coracoo/cherry:nas_rag
# 详细: rag-server/README.md

所有可选组件

组件	安装方式	用途
MCP(必须)	`pip install -e .`	90 tool,Claude Code 连 NAS
Skill	复制到 `skills/`	6 个工作流,Agent 自动触发
RAG docker	`docker compose up -d`	语义搜索,部署在 NAS 上
Dashboard	`./start.sh dashboard`	Web UI,iPhone 备忘录入口
MCP HTTP transport	`./start.sh mcp-http`	局域网/远程 MCP 客户端,Bearer 鉴权,端口 8765
百度网盘	`zspace/scripts/netdisk_login.py`	OAuth 登录后再用 28 个 znetdisk tool

用户对 Claude Code 说话                    ← 自然语言
        ↓
┌─ Skill 层(skills/) ──────────────┐
│ nas-setup / rag-manager / media-organizer│  ← LLM 触发词 → 自动加载 SKILL.md
│ ios-memo-bak / label-manager / file-org  │  ← 组合多个 MCP tool 完成复杂流程
└──────────────────┬───────────────────────┘
                   ↓ MCP 协议(stdio,JSON-RPC 2.0)
┌─ MCP 层(zspace/mcp_server/) ────────────────────┐
│ 90 个 tool(按域分文件)                    │  ← Claude Code mcp.json 配置后自动发现
│ tools/{files,storage,zvideo,notebook,    │  ← 每个 tool = 1 个 NAS API 端点封装
│        znetdisk,proxy,rag,...}           │
└──────────────────┬───────────────────────┘
                   ↓ HTTP(nas/)
┌─ 协议层(nas/,顶层共享包) ──────────────────────┐
│ auth.py  RSA 登录 + device_id 选择        │  ← Python 库,Skill 和 MCP 都复用
│ client.py NasClient(token 自动续)       │
└──────────────────┬───────────────────────┘
                   ↓ HTTP
┌─ ZSpace NAS ─────────────────────────────┐
│ :5055 主 API(文件/影视/记事本/网盘...)     │
│ :8000 RAG docker(语义搜索,可选)           │
└──────────────────────────────────────────┘

三者关系: Skill 是"做什么"(工作流) → MCP 是"怎么做"(单步操作) → nas/ 是"怎么连"(协议)。新用户只需配 MCP,skill 自动生效。

必须 & 可选

组件	必须?	说明
`.env` 配置	✅ 必须	NAS 连接信息(NAS_HOST/USER/PASSWORD)
`zspace.mcp_server`(`-m` 入口)	✅ 必须	MCP stdio 服务,Claude Code 连它
`nas-setup` skill	✅ 推荐	首次跑,验证 env + 登录 + 可选组件
`rag-server/` docker	可选	RAG 语义搜索。不装也能用 86 个 tool,只是 semantic_search 不可用
`dashboard/` Dashboard	可选	Web 管理界面(iPhone 备忘录入口等)
MCP HTTP transport	可选	`./start.sh mcp-http`,局域网/远程 MCP 客户端用,端口 8765 + Bearer
百度网盘 OAuth	可选	28 个 znetdisk tool 需要先登录

安装

git clone <repo>
cd zspace-mcp-poc

# 1. 配置连接(必须)
cp zspace/.env.example .env
vi .env   # 填 NAS_HOST / NAS_USER / NAS_PASSWORD

# 2. 装 Python 依赖(必须)
./start.sh deps

# 3. 接入 Claude Code(必须)
./start.sh mcp-cfg   # 打印配置片段,粘到 ~/.config/claude-code/mcp.json
# 重启 Claude Code → 90 个 tool 自动出现

# 4. 首次验证
python skills/nas-setup/scripts/check.py
# 输出 ✅✅✅ 即可

# 5. (可选) RAG 语义搜索
cd rag-server && docker compose up -d    # 需要 NAS docker daemon

# 6. (可选) Web Dashboard
./start.sh dashboard   # http://localhost:15050

使用示例

用户在 Claude Code 里说: "给一年级教材打《一年级》标签"

Agent 内部执行流程:
  nas-setup skill 自动加载 → check.py 验证 .env/登录/RAG
    → semantic_search("一年级 教材") → MCP tool → POST NAS RAG daemon
    → 返回 3 个匹配 {path, snippet, distance}
    → Agent 过滤 distance < 1.0 的
    → save_file_label("一年级", "path1,path2") → MCP tool → NAS API
    → MCP 客户端弹 UI 让用户批准
    → ✅ 完成

文件路由

zspace-mcp-poc/
├── nas/                        NAS 协议层(顶层共享包,skill/dashboard/mcp 都直接依赖)
│   ├── auth.py           RSA 公钥 + device_id 自动选择
│   ├── proto.py          URL 公共参数
│   └── client.py         NasClient(token 自动续)
│
├── zspace/mcp_server/           MCP Server(入口 python -m zspace.mcp_server)
│   ├── __main__.py       -m 入口
│   ├── main.py           FastMCP 入口
│   └── tools/            按域分文件
│       ├── files.py      文件读写 + 标签
│       ├── storage.py    存储池/硬件/SMART/监控
│       ├── zvideo.py     极影视
│       ├── notebook.py   记事 (17)
│       ├── znetdisk.py   网盘
│       ├── proxy.py      远程访问
│       ├── shares.py     共享/下载
│       ├── media.py      音乐/相册
│       └── rag.py        RAG 语义搜索
│
├── dashboard/app/                  Web Dashboard(入口 python -m dashboard.app)
│   ├── __main__.py       -m 入口
│   ├── main.py           FastAPI + Session
│   └── routes/
│       ├── shortcut.py   iPhone 备忘录 → NAS 入口
│       ├── dashboard.py  WebUI
│       └── files.py,notebook.py,zvideo.py 文件/记事本/影视 CRUD
│
├── rag-server/       RAG docker 服务(在 NAS 独立部署，作为文件索引)
│   ├── app/server.py       /search /reindex /index /unindex /status
│   ├── Dockerfile + docker-compose.yml
│   └── README.md           REST 协议(端点表)
│
├── skills/       6 个自动化 skill
│   ├── nas-setup/       前置:验证 env/登录/可选组件
│   ├── rag-manager/     RAG 语义搜索索引管理(门控/重建/增量)
│   ├── ios-memo-bak/    iPhone 备忘录 → 极空间记事本
│   ├── media-organizer/ 极影视分类审计
│   ├── label-manager/   标签管理
│   └── file-organizer/  文件库诊断
│
├── pyproject.toml             包定义(pip install -e .)
├── docs/API.md                 NAS 全端点速查
├── docs/MCP.md                 90 tool 详细文档
└── start.sh                    一键启动(deps/mcp/dashboard/mcp-cfg)

MCP Tool 清单(90)

文件 & 存储池 & 监控(20)

Tool	读/写	用途
`list_files`	读	列目录
`file_info`	读	单文件元数据
`recent_files`	读	最近访问
`file_categories`	读	按类型统计
`list_storage_pools`	读	存储池 & 磁盘
`hardware_info`	读	硬件槽位
`smart_report`	读	SMART 磁盘健康
`system_status`	读	NAS 综合状态
`perf_snapshot`	读	SSH 实时性能
`whoami`	读	当前用户
`mkdir`	写	新建目录
`rename`	写	重命名
`move`	写	移动
`copy`	写	复制
`remove`	⚠️ 删除	不可逆,不进回收站

极影视(9)

Tool	读/写	用途
`list_video_classes`	读	分类列表(含 is_enable/is_system)
`latest_movies` / `suggested_movies` / `random_movies`	读	影片浏览
`list_video_dirs`	读	源目录
`get_video_classification_state`	读	单个分类状态
`add_video_classification`	写	新建分类
`rename_video_classification`	写	重命名分类(classification_id + new_name)
`link_folder_to_classification`	写	关联源目录(带 is_enable=0 拒绝)

记事本(17)

Tool	读/写	用途
`notebook_list/info/search`	读	浏览 & 搜索
`notebook_allclassify/classifylist`	读	分类树
`notebook_totalsize/getconfig`	读	统计 & 配置
`notebook_historyinfo/historylist`	读	历史版本
`notebook_new/modify/delete`	写	CRUD
`notebook_pin/updatelabel/movenotepad`	写	置顶/标签/移动
`notebook_newclassify/deleteclassify/updateclassify`	写	分类管理

百度网盘(28)— 需要 OAuth 登录

分组	Tool	用途
auth	`znetdisk_auth_check/token/userinfo/logout`	OAuth oob 登录
file	`znetdisk_file_list/download/upload/newdir`	云盘文件管理
task	`znetdisk_task_list/action`	传输任务
sync	`znetdisk_sync_add/list/open/close/delete/home`	NAS ↔ 云盘双向同步
autobackup	`znetdisk_autobackup_*` (7)	自动备份
share	`znetdisk_share_verify/filelist/transfer/transfer_result`	⭐ 分享链接转存
fail	`znetdisk_fail_list`	失败列表

共享 & 下载 & 远程访问(11)

Tool	用途
`samba_status / webdav_status / ftp_status / dlna_status`	共享服务状态
`list_downloads / list_shares / list_nshares`	下载 & 分享
`proxy_login / proxy_url_for_port / proxy_fetch / proxy_list_whitelist`	zos 云代理

音乐 & 相册(3)

Tool	用途
`list_songs`	歌曲列表
`list_albums`	相册列表
`list_album_feeds`	相册内容

RAG 语义搜索(3)— 需要 rag-server docker

Tool	用途
`semantic_search`	自然语言搜文件内容
`reindex`	重建索引
`index_status`	索引概况

Skill 清单(6)

Skill	触发词	用途
`nas-setup`	首次配置、验证连接	前置:验证 env/登录/可选组件(RAG)
`rag-manager`	RAG 索引、reindex	RAG 语义搜索索引生命周期管理
`ios-memo-bak`	iPhone 备忘录同步	一键配置 iPhone Shortcut → NAS 记事本
`media-organizer`	极影视整理、frds 拆分	只读审计分类/源目录/影片抽样
`label-manager`	打标签、按标签找	标签 CRUD + 反向查询
`file-organizer`	重复文件、孤儿文件	文件库只读诊断

接入标准

MCP Client(mcp.json)

{
  "mcpServers": {
    "zspace-nas": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "zspace.mcp_server"],
      "cwd": "/path/to/zspace-mcp-poc",
      "env": {
        "NAS_HOST": "192.168.x.x",
        "NAS_USER": "<phone>",
        "NAS_PASSWORD": "<password>",
        "NAS_DEVICE_ID": "<32 hex>"
      }
    },
    "zspace-nas-http": {
      "url": "http://192.168.x.x:8765/mcp",
      "headers": {
        "Authorization": "Bearer <MCP_HTTP_TOKEN from NAS .env>"
      }
    }
  }
}

(本地 Claude Code 用 zspace-nas stdio 条目;局域网/远程 MCP 客户端用 zspace-nas-http HTTP 条目,两个互不干扰,NAS 端跑 ./start.sh mcp-http 后启用)

环境变量

变量	必填	说明
`NAS_HOST`	✅	NAS IP
`NAS_USER`	✅	手机号
`NAS_PASSWORD`	✅	密码
`NAS_DEVICE_ID`	推荐	32 字符,复用已登记设备绕短信验证
`KEY_SSH`	可选	perf_snapshot 需要
`NAS_SSH_PORT`	可选	默认 57922
`NAS_RAG_URL`	可选	RAG daemon 地址,默认 `http://nas:8000`

写操作安全规则

destroy 类(remove/notebook_delete) 不进回收站,MCP 客户端弹 UI 让用户批准
状态校验(link_folder_to_classification) 目标分类 is_enable=0 时直接拒绝
标签覆盖(save_file_label) 覆盖式,打新标签前先 file_info 看现有标签

RAG docker 部署(可选)

cd rag-server
docker compose up -d    # image: coracoo/cherry:nas_rag
# 首次跑 reindex
curl -X POST http://nas:8000/reindex -H 'Content-Type: application/json' \
  -d '{"scope":"files","full":true}'

REST API 详见 rag-server/README.md(端点表)。

文档

文档	内容
`docs/API.md`	NAS 全端点速查(12 域,~900 行)
`docs/MCP.md`	90 tool 参数/返回/端点映射
`rag-server/README.md`	RAG REST 协议(端点表)
`docs/iphone-shortcut.md`	iPhone Shortcut 配置图解

License

MIT — 详见 LICENSE。欢迎 PR/Issue/Star。

CONTRIBUTING.md

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

ZSpace NAS MCP

你只需要其中一部分

MCP 用户(3 步装上)

Skill 用户(复制到你的项目)

RAG 用户(Docker 部署到 NAS)

所有可选组件

必须 & 可选

安装

使用示例

文件路由

MCP Tool 清单(90)

文件 & 存储池 & 监控(20)

极影视(9)

记事本(17)

百度网盘(28)— 需要 OAuth 登录

共享 & 下载 & 远程访问(11)

音乐 & 相册(3)

RAG 语义搜索(3)— 需要 rag-server docker

Skill 清单(6)

接入标准

MCP Client(mcp.json)

环境变量

写操作安全规则

RAG docker 部署(可选)

文档

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 112 Commits
dashboard		dashboard
docs		docs
nas		nas
rag-server		rag-server
skills		skills
tools/browser-extension		tools/browser-extension
zspace		zspace
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation

ZSpace NAS MCP

你只需要其中一部分

MCP 用户(3 步装上)

Skill 用户(复制到你的项目)

RAG 用户(Docker 部署到 NAS)

所有可选组件

必须 & 可选

安装

使用示例

文件路由

MCP Tool 清单(90)

文件 & 存储池 & 监控(20)

极影视(9)

记事本(17)

百度网盘(28)— 需要 OAuth 登录

共享 & 下载 & 远程访问(11)

音乐 & 相册(3)

RAG 语义搜索(3)— 需要 rag-server docker

Skill 清单(6)

接入标准

MCP Client(mcp.json)

环境变量

写操作安全规则

RAG docker 部署(可选)

文档

License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages