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

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.

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 live in the standalone media-naming-guide (works with any NAS / Plex / Emby / Jellyfin). This skill adds ZSpace API-specific logic: pagination, rename/move, and 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

pip install zspace-cli

# 检查连接
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       # 树形视图

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