zspace-cli

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/skyzhao1223-zspace-cli

About

Use cases: file-management

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 25, 2026.

Tools

13 read · 7 write · 3 delete · 1 not yet classified

Secrets

None asked for

Install scripts

None found

Runs as

Python package

Tools (24)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

• zspace_bigfilesFind the largest files (server-side scan)

  List the largest files under the given directories, biggest first. Use to find cleanup candidates. The NAS scans server-side, which is far faster than walking: a 7k-file tree returns in ~2 seconds versus ~765 requests and ~10 seconds client-side. Returns {complete, scanned, matched, files: [{name, path, bytes, modify_time}]}. There is a single shared task slot, so this call clears any stale task before starting one; that is harmless but means two concurrent bigfiles scans would interfere. Check `complete` -- if the timeout elapsed the results are partial. Read-only. For a directory's total …

• zspace_checkCheck ZSpace NAS connection

  Check whether the ZSpace NAS is reachable through the local desktop client proxy and, if so, return a summary of storage pools. Call this first to verify the proxy at 127.0.0.1:13579 is online before running other file operations. Returns {"connected": true, "pools": [{name, total_tb, free_tb}]} when the NAS responds, or {"connected": false} when it does not. Never modifies NAS state. Unlike zspace_pool_info, this is a connectivity probe that happens to include a pool summary; use pool_info when you only need capacity.

• zspace_copyCopy files or directories

  Copy one or more files/directories on the NAS into a destination folder. Use to duplicate media or create backups without removing the originals. Accepts a single path or a list; the destination must already exist (create it with zspace_mkdir). Returns {status: "copied", paths, to}. Mutates NAS state but leaves the sources untouched. The non-destructive counterpart of zspace_move — pick copy when the original must stay where it is, move when it should not. Copies consume additional capacity; check zspace_pool_info first for large trees.

• zspace_disk_statsGet disk statistics

  Return raw disk statistics reported by the ZSpace NAS. Use for diagnostics and health monitoring (I/O, capacity, SMART-style counters as exposed by the NAS API). Returns the raw stats object. Read-only; never modifies NAS state. Unlike zspace_pool_info, the shape is whatever the NAS API exposes and is not normalized — choose pool_info for "how much free space", this one for "is a disk unhealthy".

• zspace_disksPer-disk capacity, health and free bays

  Report every physical disk: free space, temperature, health, SMART counters, fragmentation and power-on hours, plus how many bays are empty. Use before recommending a drive purchase or when a pool is nearly full -- pool-level free space can be misleading, since in a ZDR pool the space may all sit on one spindle while another is effectively full (observed: a pool reporting 476 GiB free had one disk with only 59.8 GiB left). Returns {free_bays: {sata, nvme, esata}, disks: [{pool, position, model, sn, dev_type, total_bytes, free_bytes, used_pct, temp_c, health, power_on_hours, reallocated_secto…

• zspace_downloadDownload file from NAS

  Download a file from the ZSpace NAS to a local directory. Use to pull media or documents off the NAS. The local_dir must already exist. Returns {saved_to: "<absolute local path>"}. Does not modify NAS state. NAS -> local, the inverse of zspace_upload. Unlike upload this never changes anything on the NAS, so it is safe to retry; an existing local file of the same name is overwritten.

• zspace_duDirectory size and file count

  Get the size, file count and directory count of one NAS directory. Returns {path, bytes, files, dirs, state, complete, source, categories}. **Always check `complete` before reporting the numbers.** The server-side statistic is instant and exact for small-to-medium trees, but on large ones the NAS returns state="running" with a partial snapshot that never converges -- measured on a 1.175 TiB / 448k-file folder, fourteen consecutive calls all reported ~0.35 TiB with the file count jittering between 27k and 30k. There is no poll endpoint that works, so when `complete` is false either pass walk=…

• zspace_infoGet file or directory info

  Return detailed metadata for one file or directory on the ZSpace NAS. Use when you need more than the ls summary exposes (permissions, timestamps, exact size, type details). Returns the raw info object from the NAS API. Read-only; the path must already exist. One path only — use zspace_ls to enumerate a directory, or zspace_search to locate an item first.

• zspace_lsList directory contents

  List the contents of a directory on the ZSpace NAS at the given path. Use to browse files, locate items, or pick targets for later move/copy operations. Large directories are paginated automatically (the NAS API returns at most 50 entries per call). Returns a list of {name, path, is_dir, size} objects. Read-only; pass show_hidden=True to include hidden entries. Flat and one level deep: use zspace_tree for nested structure, zspace_search when you know a name but not the location, and zspace_info for full metadata on one path you already have.

• zspace_mkdirCreate directory

  Create a new directory on the ZSpace NAS under the given parent. Use to prepare a destination before moving files into it. name is the bare basename, not a path. Fails if a directory of that name already exists. Returns the created {name, path}. Mutates NAS state. zspace_move and zspace_copy both require the destination to exist already, so call this first when reorganizing into a new folder.

• zspace_moveMove files or directories

  Move one or more files/directories on the NAS into a destination folder. Use to reorganize files, e.g. sort media into per-genre folders. Accepts a single path or a list; the destination must already exist (create it with zspace_mkdir). Returns {status: "moved", paths, to}. Mutates NAS state; sources are removed from their original location. Choose move vs copy by whether the originals should survive: copy keeps them, move does not. To change only the name within the same directory, use zspace_rename instead.

• zspace_pool_infoGet storage pool info

  List every storage pool on the ZSpace NAS with its name and capacity. Use to inspect free space before an upload or to report total capacity. Returns a list of {name, total_tb, free_tb} objects, one per pool. Read-only; never modifies NAS state. Prefer this over zspace_disk_stats for capacity questions: it returns normalized per-pool numbers, whereas disk_stats returns the NAS's raw diagnostics object. Use zspace_check instead if you need to know whether the NAS is reachable at all.

• zspace_recycle_configRecycle bin retention policy

  Read the recycle bin retention policy: {my_cycle, public_cycle} in days. -1 means never auto-purge, which is the factory default -- so deleted data keeps occupying pool space indefinitely until something empties the bin. If a user reports that deleting files did not free space, check this first. Read-only; there is deliberately no MCP tool for changing it.

• zspace_recycle_emptyEmpty an entire recycle bin

  Permanently purge an entire recycle bin. **Irreversible, and this is the only way deleted files actually stop occupying pool space.** Two things make this easy to get wrong. First, the personal and public bins are separate stores: emptying the public bin after deleting from a personal space succeeds with total_num=0 and frees nothing. Second, it purges EVERYTHING in that bin, not just what the current task deleted. Always call zspace_recycle_list first, show the user the contents, and get their agreement. Requires confirm=true. Returns the server task summary {total_num, succeed_num, fail_nu…

• zspace_recycle_listList recycle bin contents

  List what is currently in a recycle bin, including each item's original location. **Always call this before zspace_recycle_empty** -- emptying purges every item in the bin, including files deleted earlier by other means, and is irreversible. The personal and public bins are separate stores; files deleted from /<pool>/my/data land in the personal one. The listing triggers a server-side scan and this call waits for it to settle, so an in-progress scan is not mistaken for an empty bin. Returns {bin, total, items: [{name, path, original_path, is_dir, bytes}]}. The `path` is the in-bin location a…

Signals

Stars

28

Forks

5

Open issues

1

Contributors

5

Weekly downloads

200

Last commit

Oct 9, 2026 (21 days ago)

Last release

Oct 9, 2026 (22 days ago)

Last package publish

Oct 9, 2026 (22 days ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name

io.github.skyzhao1223/zspace-cli

Version

0.1.13

Auth

No auth

Packages

pypi zspace-cli

License

MIT

Repository

github.com/skyzhao1223/zspace-cli

First seen

Oct 24, 2026

Last checked

Oct 24, 2026

Source

Official MCP Registrygithub-graphql