filemayor-mcp

The FileMayor MCP server. Drive your intelligent filesystem clerk from Claude, Cursor, Zed, or any Model Context Protocol client.

v4.2.1 · Node ≥20 · filemayor.com/mcp

Install

npm install -g filemayor-mcp

Or run without installing:

npx -y filemayor-mcp

Wire it into Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "filemayor": {
      "command": "npx",
      "args": ["-y", "filemayor-mcp"]
    }
  }
}

Restart Claude. You'll see the FileMayor tools in the 🔧 menu.

No API key needed. When Claude is the client, Claude IS the AI — it calls filemayor_explain to audit the folder, reasons about the moves, and passes them directly to filemayor_apply. The filemayor_plan tool (which calls an external AI) is only for non-Claude clients.

Wire it into Cursor / Zed / other MCP clients

Any client that speaks MCP over stdio works. Point it at filemayor-mcp and you're done.

Tools exposed

| Tool | What it does | |:---|:---| | filemayor_scan | List every file in a directory tree with size + category. | | filemayor_analyze | Deep audit: duplicates, bloat, junk, largest dirs. | | filemayor_explain | Folder health score (0–100), atomic bundles, insights. | | filemayor_plan | For non-Claude clients: AI-generated plan using whichever key is set (ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY). When Claude is the client, skip this — Claude reasons directly. | | filemayor_apply | Execute the most recent plan from filemayor_plan. | | filemayor_rollback | Reverse the most recent applied plan. | | filemayor_organize | Deterministic auto-organize by extension (no AI). | | filemayor_para | Sort by actionability — PARA method (Projects/Areas/Resources/Archives). Deterministic, returns a reviewable plan + ready-to-apply moves. No AI key needed. | | filemayor_clean | Find junk files (temp, cache, .DS_Store, Thumbs.db). | | filemayor_duplicates | Hash-based duplicate detection. | | filemayor_dedupe | Find AND remove duplicates (content-hash). Trash-based — reversible with rollback. | | filemayor_delete_files | Delete file paths with hardened-runtime validation. Trash-based — reversible. | | filemayor_history | Recent move journal. | | filemayor_undo_last | Undo the last N moves. | | filemayor_info | Version, runtime, license tier. |

The Curative Triad

The headline workflow:

filemayor_explain → filemayor_plan → filemayor_apply
       ↓                  ↓                ↓
   "diagnose"        "propose"        "execute"
   (always safe)   (no mutations)   (journaled)

Every applied plan can be reversed with filemayor_rollback.

Security & threat model

A recent viral post warned about MCP servers exposing API keys, email access, AWS infrastructure maps, and clinical-trial data to anonymous internet scans. The threat is real for some MCP servers — but it doesn't generalize. Here's exactly where FileMayor sits against each part of that threat model, plus how you can verify the claims yourself.

Self-audit (verify before you trust)

Before you wire this server into your MCP client, run:

npx -y filemayor-mcp --audit

It prints a structured JSON report — transport type, network listeners, outbound destinations, tool list (with destructive flags), runtime safeguards, and a verifyBy checklist. The report exits with code 0 and does not start an MCP session, so you can run it on any machine, diff it across upgrades, or pipe it into your own checks.

Threat-by-threat

1. "Scannable from the internet · no auth · exposed credentials"

Doesn't apply. FileMayor MCP uses stdio transport only. The server is launched as a subprocess of your MCP client (Claude Desktop, Cursor, Zed, Continue) and communicates over the subprocess's stdin/stdout. There is no HTTP listener, no SSE endpoint, no WebSocket, no port to scan. --audit confirms transport.networkListeners: false.

2. "Starlette / FastAPI / Python CVE"

Doesn't apply. FileMayor MCP is Node.js, not Python. Its single runtime dependency is @modelcontextprotocol/sdk (the official Anthropic Node SDK). No Starlette, no FastAPI, no ASGI, no Python in the runtime path. --audit confirms dependencies.python: false.

3. "A tool's stated purpose hides exfiltration" (e.g., a summarize_webpage tool that also emails out credentials)

This is the supply-chain risk that applies to every MCP server in principle, ours included. Our mitigations:

• The whole server is one file, and the published package is the source — read index.mjs on unpkg or the npm Code tab end-to-end in about 15 minutes. Tool declarations and their case handlers sit side-by-side. (--audit prints the exact current line count under verifyBy, so the number can't drift out of date.)
• grep -E "fetch\(|http\.request|https\.request|net\." mcp/index.mjs returns nothing. The server makes no outbound network calls of its own.
• The only off-machine egress path is the optional AI call inside filemayor_plan, gated by an AI provider key (ANTHROPIC_API_KEY → Claude, GEMINI_API_KEY → Gemini, or OPENAI_API_KEY → GPT-4o-mini). The first key present wins. Without any key, the tool returns an error and nothing is sent. With a key, only directory metadata (paths, sizes, extensions) is sent — no file contents. When Claude is the MCP client, filemayor_plan is not needed at all.
• The npm registry is the canonical distribution: what you read on unpkg is byte-for-byte what npx runs (verify with npm view filemayor-mcp dist.integrity).

What --audit reports

{
  "package": "filemayor-mcp",
  "version": "4.2.1",
  "transport": { "type": "stdio", "networkListeners": false, "ports": [] },
  "outbound": {
    "defaultEgress": "none",
    "optionalEgress": {
      "enabled": false,
      "destinations": [
        "https://api.anthropic.com",
        "https://generativelanguage.googleapis.com",
        "https://api.openai.com"
      ],
      "trigger": "filemayor_plan tool only (not used when Claude is the MCP client)",
      "payload": "directory metadata only — no file contents",
      "gatedBy": "one of ANTHROPIC_API_KEY / GEMINI_API_KEY / OPENAI_API_KEY (none currently set)"
    }
  },
  "runtimeSafeguards": {
    "pathJailing": true,
    "systemDirBlocking": true,
    "symlinkResolution": true,
    "journaledMoves": true,
    "rollbackAvailable": true
  },
  "tools": [ /* 15 entries, each with `destructive: true|false` */ ],
  "dependencies": { "runtime": ["@modelcontextprotocol/sdk"], "python": false, "starlette": false, "fastapi": false },
  "source": "https://unpkg.com/filemayor-mcp/index.mjs",
  "verifyBy": [
    "Read index.mjs end-to-end at https://unpkg.com/filemayor-mcp/index.mjs — the report prints the exact current line count here.",
    "grep for outbound calls in your local install: rg \"fetch\\(|http\\.request|https\\.request|net\\.\" $(npm root -g)/filemayor-mcp/index.mjs",
    "Run `npm view filemayor-mcp dist.integrity` and compare against your node_modules copy.",
    "Run this same `--audit` after upgrading to detect changes to transport / egress / tool list."
  ]
}

A note on third-party "MCP audit" tools

A viral tutorial recommended pip install mcp-audit && mcp-audit scan to audit installed MCP servers. As of this release, mcp-audit is not published on PyPI, and the mcp-audit package on npm is a 408-byte hello-world stub (v0.0.1, published April 2025, no functional code). The tutorial directs viewers to comment on a social-media post to receive the "real" tool by direct message — that's a social-engineering pattern, not a verifiable tool. Be skeptical of any installer not on a public registry under a known maintainer.

If a real, signed, open-source MCP scanner emerges, we'll link to it from this section and publish the verdict against filemayor-mcp. Until then, --audit + reading the ~580 lines of source is the trustworthy path.

Hardened-runtime safeguards (the engine, not just the MCP shell)

Every tool that touches disk runs through the same security layers the CLI and Desktop app use:

| Layer | Purpose | |:---|:---| | Path jailing | Symlinks resolved before validation. System dirs (/System, C:\Windows, /etc, /proc, …) are blocked. | | Plan-then-apply gate | _explain and _plan are read-only. Only _apply mutates disk. | | Journaled moves | Every move is recorded to a write-ahead log on disk. | | Rollback | _rollback reverses the last applied plan; _undo_last rolls back N specific moves. The journal survives crashes. | | No-telemetry | The MCP server makes no analytics calls. The only off-machine call is the documented, opt-in AI planner in filemayor_plan (not used when Claude is the client). |

License

Proprietary — © 2026 Lehlohonolo Goodwill Nchefu (Chevza)