ZSpace NAS MCP

ZSpace NAS MCP

Enables AI agents like Claude Code to directly control a ZSpace NAS with 90 tools for file management, media, notes, cloud disks, and more.

Category
访问服务器

README

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

写操作安全规则

  1. destroy 类(remove/notebook_delete) 不进回收站,MCP 客户端弹 UI 让用户批准
  2. 状态校验(link_folder_to_classification) 目标分类 is_enable=0 时直接拒绝
  3. 标签覆盖(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

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选