Skip to main content
Glama
Sign In
wiztree-mcp

wiztree-mcp

by bigmanBass666
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

wiztree-mcp

基于 WizTree 的磁盘分析 MCP 服务器 — 通过 MCP 工具扫描驱动器、查询磁盘使用情况、搜索路径、比较快照以及可视化文件系统数据。

// Claude Code 配置
{
  "mcpServers": {
    "wiztree": {
      "command": "wiztree-mcp"
    }
  }
}

功能特性

🗂️ 扫描

  • scan_disk — 用 WizTree 扫描驱动器/文件夹并将结果导入 SQLite。内存高效流式处理（无需将完整 CSV 加载到内存）。

📋 查询

  • list_scans — 列出所有历史扫描记录

  • disk_summary — 详细概览（容量、文件数、文件夹数、Top N）

  • top_entries — 按大小排序的最大文件/文件夹

  • drill_down — 浏览指定文件夹的内容

🔍 搜索

  • search_paths — 关键字/通配符路径搜索，附带汇总大小

  • file_type_summary — 按文件扩展名统计磁盘使用情况

  • large_old_files — 查找长期未修改的大文件

🔄 比较

  • compare_scans — 两次扫描的差异报告（增长 + 缩减）

🛠️ 管理

  • get_treemap — 获取树图可视化（若扫描时已生成）

  • cleanup_scans — 清理旧扫描，仅保留最近 N 次

Related MCP server: File Search Tool

安装

pip install wiztree-mcp

需要 Python 3.10+ 和 WizTree（免费，diskanalyzer.com）。

WizTree 设置

  1. 安装 WizTree（64 位）

  2. 确保 WizTree64.exe 在 PATH 中或位于标准安装位置，或设置 WIZTREE_PATH 环境变量：

    set WIZTREE_PATH=D:\apps\WizTree\WizTree64.exe

使用

启动服务器

wiztree-mcp

这将在 STDIO 上启动 MCP 服务器——这是 Claude Code 等 MCP 主机的标准传输方式。

扫描驱动器

# 通过 MCP 工具（在 Claude Code 或任意 MCP 主机中）
await mcp.call_tool("scan_disk", {"target_path": "C:"})

查询结果

await mcp.call_tool("disk_summary", {"scan_id": 1})
await mcp.call_tool("top_entries", {"scan_id": 1, "kind": "files", "limit": 20})
await mcp.call_tool("search_paths", {"scan_id": 1, "query": "node_modules"})
await mcp.call_tool("drill_down", {"scan_id": 1, "folder_path": "C:\\Users"})

比较扫描

await mcp.call_tool("compare_scans", {
    "scan_id_before": 1,
    "scan_id_after": 2,
})

环境变量

变量

说明

WIZTREE_PATH

WizTree64.exe 的路径（覆盖自动检测）

WIZTREE_MCP_DATA_DIR

数据库和导出 CSV 的存储目录（默认：~/.local/share/wiztree-mcp/）

架构

┌─────────────────────────────────────────────────┐
│                 MCP 主机 (Claude Code)           │
├─────────────────────────────────────────────────┤
│  STDIO 传输 ──── wiztree-mcp 服务器              │
│                         │                       │
│  ┌──────────────────────┴──────────────────┐    │
│  │  FastMCP (mcp SDK)                     │    │
│  │  ├── 11 个工具 via @mcp.tool()         │    │
│  │  └── Lifespan (DB 生命周期管理)        │    │
│  ├────────────────────────────────────────┤    │
│  │  数据库 (SQLite)                       │    │
│  │  ├── scans 表 (元数据)                 │    │
│  │  ├── entries 表 (文件 + 文件夹)        │    │
│  │  └── 6 个索引用于快速查询              │    │
│  ├────────────────────────────────────────┤    │
│  │  WizTree CLI                           │    │
│  │  └── WizTree64.exe /export=...         │    │
│  └────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

关键设计决策：

  • CSV → SQLite 流式处理：CSV 逐行解析并插入 SQLite。无论 CSV 多大，内存占用始终不超过 ~50 MB。

  • SQL 查询：所有工具使用索引 SQL 查询（O(log n)），而非数组遍历（O(n)）。

  • 持久化：数据在服务器重启后仍然保留。跨会话比较即 SQL JOIN。

  • 零额外依赖：仅 mcp SDK。csv 和 sqlite3 均为 Python 标准库。

开发

git clone https://github.com/onmokoworks/wiztree-mcp
cd wiztree-mcp
python -m venv .venv
.venv\Scripts\activate  # Windows
pip install -e .
python tests/test_db_quick.py
python tests/test_csv_importer.py

性能

指标

之前 (TypeScript)

之后 (Python + SQLite)

CSV 解析 (400 MB)

~210 秒, 1-2 GB 内存

~30 秒, <50 MB 内存

查询

O(n) 数组扫描

O(log n) SQL 索引

持久化

无（内存缓存）

SQLite 永久存储

跨会话比较

完整加载 2 个 CSV

SQL JOIN（毫秒级）

启动

~5 秒（解析 CSV）

~50 毫秒（打开数据库）

依赖项

csv-parse + zod + sdk

仅 mcp（CSV + SQLite 使用 Python 标准库）

许可证

MIT

Available Tools

11 tools
cleanup_scansA

Remove older scans from the database to free up space.

Keeps the N most recent scans and deletes everything older. Entries are cascade-deleted when their parent scan is removed.

Args: keep_latest: Number of most recent scans to keep (default 5, min 1). ctx: MCP context (injected automatically).

Returns: Report of which scans were deleted.

Inputs: keep_latest. Returns: result

compare_scansA

Compare two scans of the same drive to see what changed.

Use this to measure cleanup results, track growth over time, or identify which directories changed the most between two points.

Args: scan_id_before: The earlier scan ID (the "before" snapshot). scan_id_after: The later scan ID (the "after" snapshot). limit: Number of top changes to show (default 20, max 100). ctx: MCP context (injected automatically).

Returns: Comparison report with capacity changes and top growth/shrink paths.

Inputs: scan_id_after (required), scan_id_before (required), limit. Returns: result

disk_summaryA

Get a detailed summary of a disk scan.

Returns drive info, capacity, total files/folders, and the top N largest files and folders.

Args: scan_id: The scan ID (use list_scans to find available scans). top_n: Number of top files and folders to include (default 20, max 100). ctx: MCP context (injected automatically).

Returns: Formatted summary string.

Inputs: scan_id (required), top_n. Returns: result

drill_downA

Browse the contents of a specific folder (drill down).

Shows all entries inside the given folder path, sorted by size descending. Useful for interactively exploring large directories step by step.

Args: scan_id: The scan ID. folder_path: The folder path to drill into (e.g., "C:\Users", "D:\Projects\src"). limit: Number of entries to return (default 50, max 200). offset: Pagination offset for seeing more items. ctx: MCP context (injected automatically).

Returns: List of sub-entries (files and folders) inside the given path.

Inputs: scan_id (required), folder_path (required), limit, offset. Returns: result

file_type_summaryA

Summarize disk usage by file extension type.

Groups all files by their extension and returns a ranked list of which file types consume the most space.

Args: scan_id: The scan ID. limit: Number of extensions to show (default 30, max 100). ctx: MCP context (injected automatically).

Returns: Ranked table of file extensions by total size.

Inputs: scan_id (required), limit. Returns: result

get_treemapA

Get a treemap visualization image for a scan (if generated during scan).

Note: treemap images are only available if the scan was run with treemap=True in scan_disk.

Args: scan_id: The scan ID to retrieve the treemap for. ctx: MCP context (injected automatically).

Returns: PNG image content of the treemap visualization.

Inputs: scan_id (required). Returns: Image content for a message.

large_old_filesA

Find files that are both large and haven't been modified recently.

These are prime candidates for cleanup — files taking up significant space that haven't been touched in a long time.

Args: scan_id: The scan ID. older_than_days: Minimum age in days (default 180, ~6 months). min_size_mb: Minimum file size in MB (default 100). limit: Maximum results (default 50, max 200). ctx: MCP context (injected automatically).

Returns: List of large, old files sorted by size descending.

Inputs: scan_id (required), limit, min_size_mb, older_than_days. Returns: result

list_scansA

List all previous disk scans stored in the database.

Returns a table with scan ID, drive, label, scan time, and capacity info. Use this to find scan IDs for other tools like disk_summary or top_entries.

Args: ctx: MCP context (injected automatically).

Returns: Formatted list of all scans.

Inputs: no named parameters. Returns: result

scan_diskA

Scan a drive or folder with WizTree and import results into the database.

This is the primary data ingestion tool. It:

  1. Locates the WizTree CLI executable

  2. Runs WizTree to export CSV (and optional treemap PNG)

  3. Streams the CSV into SQLite (memory-efficient, <50 MB)

  4. Returns a scan summary

After scanning, use other tools (disk_summary, top_entries, etc.) to query the results.

Args: target_path: Drive or folder to scan (e.g., "C:", "D:\Projects"). label: Optional human-readable label for this scan (e.g., "Cleanup Prep"). max_depth: Maximum folder depth to export (None = unlimited). Use a small value like 5 to reduce CSV size for quick scans. export_folders: Include folder entries in the export. export_files: Include file entries in the export. treemap: Also generate a treemap PNG image alongside the CSV. timeout: Maximum seconds to wait for the WizTree scan to complete. ctx: MCP context (injected automatically).

Returns: JSON string with scan result summary.

Inputs: target_path (required), label, timeout, treemap, +3 more. Returns: result

search_pathsA

Search for paths in a scan by keyword.

Useful for finding specific directories or files (e.g., "node_modules", "cache", "npm", "temp").

Args: scan_id: The scan ID. query: Search keyword or path fragment (case-insensitive). kind: Entry type — "all" (default), "files", or "folders". limit: Maximum results to return (default 50, max 200). ctx: MCP context (injected automatically).

Returns: Matching entries with total aggregate size.

Inputs: query (required), scan_id (required), kind, limit. Returns: result

top_entriesA

List the largest entries in a scan (files, folders, or both).

Args: scan_id: The scan ID. kind: Entry type — "files" (default), "folders", or "all". limit: Number of entries to return (default 20, max 500). offset: Pagination offset (default 0). ctx: MCP context (injected automatically).

Returns: Formatted table of entries sorted by size descending.

Inputs: scan_id (required), kind, limit, offset. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.3/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: scanning, listing, summarizing, comparing, searching, drilling down, file type analysis, large old files, cleanup, and treemap retrieval. No two tools overlap in functionality.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., scan_disk, list_scans, compare_scans). The naming is predictable and intuitive.

    Tool Count5/5

    11 tools cover the full domain of disk scanning, browsing, analysis, comparison, cleanup, and visualization without being excessive. Each tool earns its place.

    Completeness4/5

    The tool set covers the full lifecycle from scanning to analysis to cleanup. Minor gaps exist: no tool to delete a specific scan (only bulk cleanup of old scans) and no way to update scan metadata. Still, the surface is nearly complete.

    Resources

    Related MCP Connectors

    Related MCP Servers

    • WizTree MCP

      onmokoworks
      A
      license
      B
      quality
      C
      maintenance
      Read-only MCP server that wraps WizTree's CSV export and adds disk-usage analysis tools, enabling file system scanning and analysis via natural language.
      6
      105 npm
      4
      MIT

    • File Search Tool

      RJTPP
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables file system search and inspection, including directory listing, regex-based file name and content searches, and reading text, PDF, and DOCX files.
      1
      MIT

    • PacketMaster

      Jctechbr
      F
      license
      B
      quality
      C
      maintenance
      MCP server for network-troubleshooting PCAP analysis via tshark, enabling users to analyze PCAP files, detect anomalies, and troubleshoot network issues.
      22
      -