zspace-cli

CLI, SDK & MCP Server for ZSpace (极空间) NAS

Manage your 极空间 NAS files from the terminal, Python scripts, or AI agents — zero config, no SSH needed.

English | 中文

---

Why zspace-cli?

ZSpace (极空间) is a popular NAS brand in China, but it lacks official CLI tools or developer APIs.

zspace-cli reverse-engineered the internal API used by the ZSpace desktop client and wraps it into:

• zs CLI — 10 commands covering all file operations, powered by Rich for beautiful output
• Python SDK — ZSpaceClient with a clean, typed interface for automation scripts
• MCP Server — one-line config to add ZSpace file management to Claude, Cursor, or any MCP-compatible AI agent

Zero Configuration

Just install and run. zspace-cli reads auth tokens directly from your running ZSpace desktop client — no passwords, no SSH keys, no port forwarding.

pip install zspace-cli
zs check   # ✓ Connected, 11.8 TB total, 1.2 TB free
zs ls      # List your NAS files

---

Features

Operation	CLI	SDK	MCP
List directory	zs ls [path]	client.ls(path)	zspace_ls
File info	zs info <path>	client.info(path)	zspace_info
Rename	zs rename <path> <name>	client.rename(path, name)	zspace_rename
Create dir	zs mkdir <parent> <name>	client.mkdir(parent, name)	zspace_mkdir
Move	zs mv <src> <dest>	client.move(src, dest)	zspace_move
Copy	zs cp <src> <dest>	client.copy(src, dest)	zspace_copy
Delete	zs rm <path>	client.remove(path)	zspace_remove
Search	zs find <keyword>	client.search(kw)	zspace_search
Tree view	zs tree [path]	client.tree(path)	zspace_tree
Health check	zs check	client.is_connected()	zspace_check

---

Installation

pip install zspace-cli

Prerequisites: ZSpace desktop client running on macOS (logged in).

With MCP Server support

pip install "zspace-cli[mcp]"

---

Quick Start

CLI

# Check connection
zs check

# List files
zs ls /sata11/my/data
zs ls -l /sata11/my/data/影视    # detailed view

# File operations
zs mkdir /sata11/my/data 新建文件夹
zs rename /sata11/my/data/old_name new_name
zs mv /sata11/my/data/file.mp4 /sata11/my/data/影视
zs cp /sata11/my/data/important /sata11/my/data/backup
zs rm /sata11/my/data/temp

# Search & explore
zs find "权力的游戏"
zs tree /sata11/my/data -d 3

Python SDK

from zspace_cli import ZSpaceClient

with ZSpaceClient() as zs:
    # List files
    for f in zs.ls("/sata11/my/data"):
        print(f"{'📁' if f.is_dir else '📄'} {f.name}")

    # Batch rename videos
    for f in zs.ls("/sata11/my/data/影视"):
        if f.name.startswith("[raw]"):
            new_name = f.name.replace("[raw]", "").strip()
            zs.rename(f.path, new_name)
            print(f"Renamed: {new_name}")

    # Organize files
    zs.mkdir("/sata11/my/data", "已整理")
    zs.move("/sata11/my/data/散文件.pdf", "/sata11/my/data/已整理")

MCP Server (for AI Agents)

Add to your Claude Desktop / Cursor MCP config:

{
  "mcpServers": {
    "zspace": {
      "command": "zs-mcp",
      "args": []
    }
  }
}

Then ask your AI: "帮我把 NAS 上影视文件夹里的视频按年份整理一下"

---

How It Works

┌─────────────┐      ┌──────────────────┐      ┌──────────┐
│  zs CLI     │      │  ZSpace Desktop  │      │  ZSpace  │
│  Python SDK ├─────►│  Client (proxy)  ├─────►│  NAS     │
│  MCP Server │ HTTP │  127.0.0.1:13579 │ P2P  │  Device  │
└─────────────┘      └──────────────────┘      └──────────┘

The ZSpace desktop client maintains an encrypted tunnel to your NAS and exposes a local HTTP proxy. zspace-cli communicates with this proxy using the same API the official web UI uses.

No direct network access to the NAS is needed — works even when your NAS is behind NAT or on a different network.

---

API Reference

All operations go through the ZSpace internal API at 127.0.0.1:13579.

Endpoint	Method	Key Parameters
/v2/file/list	POST	path, show_hidden
/v2/file/info	POST	path
/v2/file/modify	POST	path, newname
/v2/file/newdir	POST	parent (not path!), name, rename=0
/v2/file/move	POST	paths[] (array), to (not dest!)
/v2/file/copy	POST	paths[] (array), to (not dest!)
/v2/file/remove	POST	paths[] (array)

Key discovery: The parameter names are non-standard — newdir uses parent instead of path, and move/copy use to instead of dest. These were found by reverse-engineering the ZSpace web UI.

---

Skills

Media Manager

A Cursor AI Skill for organizing movies and TV series on your ZSpace NAS. See skills/media-manager/ for details.

Naming conventions and general methodology are defined in the standalone media-naming-guide — this skill adds ZSpace API-specific logic (pagination, rename, move, content verification).

---

Roadmap

• File upload/download support
• Linux client support
• Windows client support
• Docker image for headless deployment
• Batch operations with glob patterns
• File watching / sync triggers

---

Contributing

Contributions are welcome! Please open an issue first to discuss what you'd like to change.

---

License

MIT

---

中文说明

功能特性

zspace-cli 是极空间 NAS 的命令行工具、Python SDK 和 MCP Server。

通过逆向工程极空间桌面客户端的内部 API，实现了完整的文件管理功能——无需 SSH，无需 WebDAV，零配置即可使用。

安装

pip install zspace-cli

前提条件： macOS 上已安装并登录极空间桌面客户端。

使用方法

# 检查连接
zs check

# 文件操作
zs ls                             # 列出目录
zs ls -l /sata11/my/data/影视     # 详细模式
zs info /sata11/my/data/影视      # 查看详情
zs mkdir /sata11/my/data 新文件夹  # 创建目录
zs rename /path/old new_name       # 重命名
zs mv /path/src /path/dest         # 移动
zs cp /path/src /path/dest         # 复制
zs rm /path/to/delete              # 删除
zs find "关键词"                    # 搜索
zs tree /sata11/my/data -d 3       # 树形视图

MCP Server 配置（AI 智能体）

在 Claude Desktop 或 Cursor 的 MCP 配置中添加：

{
  "mcpServers": {
    "zspace": {
      "command": "zs-mcp",
      "args": []
    }
  }
}

配置完成后，你可以用自然语言让 AI 管理你的 NAS 文件：

• "帮我把影视文件夹里的电影按年份分类"
• "查找所有大于 10GB 的文件"
• "把百度网盘文件夹里的文档移到文档同步文件夹"

Cursor Skill: 影视文件管理

内置 Cursor AI Skill，可以让 AI 帮你整理 NAS 上的影视资源。详见 skills/media-manager/。

命名规范和通用方法论见独立项目 media-naming-guide。

工作原理

极空间桌面客户端在本机 127.0.0.1:13579 建立了到 NAS 的加密代理。zspace-cli 通过这个代理调用和官方 Web UI 完全相同的 API，因此：

• 不需要 NAS 在局域网内
• 不需要配置 DDNS 或端口转发
• 不需要开启 SSH
• 只要桌面客户端在运行，就能操作