SassyMCP

One MCP server to replace them all.

278 tools | 39 modules | 18 tool groups | Replaces 75+ MCP servers | ~35MB standalone exe

Last updated: 2026-09-21 — v1.16.0 | all tools unlocked; optional supporter license

Compatible with Claude Desktop, Grok Desktop, Cursor, Windsurf, and any MCP client.

The official GitHub MCP server has critical SHA-handling bugs. SassyMCP's GitHub module uses correct blob SHA lookups, proper path encoding, atomic multi-file commits via Git Data API, retry logic with exponential backoff, and rate-limit awareness. It's a drop-in replacement that actually works.

Why SassyMCP?

The MCP ecosystem is fragmented. Need file operations? Install Filesystem server. Need terminal? Desktop Commander. GitHub? Another server. Android? Another. Screenshots? Another. You end up with 6-10 separate MCP servers, each consuming context window, each with its own config, bugs, and update cycle.

SassyMCP replaces 75+ individual MCP servers — including Desktop Commander (5.9k stars), Windows-MCP (5k stars), GitHub MCP Server (28.6k stars), Anthropic's official Filesystem and Memory servers, mobile-mcp (4.4k stars), and dozens more — with a single ~35MB exe.

Key differentiators:

• Smart Tool Loading — Only loads tool groups you use. Reduces context window overhead from ~25K tokens to ~5K tokens by default.
• Dynamic Vision — Real-time screen monitoring with change detection for both desktop and Android. No more screenshot-and-pray.
• Android Interaction — Full phone control via UI accessibility tree: tap, swipe, type, with automatic sensitive context detection (auth/payment screens auto-block).
• Pause/Resume — User takes over the phone for manual steps (login, 2FA, account selection), AI watches and learns, then resumes autonomously.
• Usage Tracking — ML-lite scoring of tool invocations with exponential decay. Your most-used tools load first.
• Context Estimation — Built-in tool to measure how much of your 200K context window tool definitions consume.
• Response Minification — GitHub API responses stripped of URL metadata bloat (40-70% smaller).
• Safe Delete — Delete commands (rm, del, Remove-Item, etc.) are intercepted across all shells. Instead of destroying files, targets are moved to a _DELETE_/ staging folder in the same directory for human review — protecting against AI hallucinations.
• Guided Setup — Wizard walks through persona, GitHub token, SSH credentials, and optional tool discovery.

What It Replaces

Plus features with no MCP server equivalent: phone pause/resume with sensitive context detection (auto-blocks on login/payment screens), operational hooks (14 expert playbooks), safe delete interception, Windows autorun forensics, Android+Windows clipboard sync, usage-weighted smart loading.

Licensing

Every tool group ships unlocked, for everyone, with no key required. As of v1.13.0 the release model is all-or-nothing — there is no free/pro split, no gated groups, no crippled demo. The 278 tools you see in the module table below are the product, out of the box.

Supporter licenses (optional): SassyMCP can still be purchased through LemonSqueezy as a one-time supporter license (no subscriptions). Activating a key registers your machine as a seat and records a supporter tier that shows in the startup banner, control panel, and VS Code cockpit — all tools are unlocked regardless of tier. Buy once to support development; refunds revoke the label automatically.

Activation flow (supporters):

1. Purchase at https://sassyconsultingllc.com/store — LemonSqueezy emails you a key (XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX).
2. Activate from your AI agent: sassy_setup_license action=activate key=...
3. Or from a terminal: sassymcp.exe setup opens the interactive menu.

Offline operation: Once activated, a local HMAC-signed payload lets the supporter tier validate fully offline. A weekly re-check against LS catches refunds and cancellations; a faster startup check against the SassyMCP billing oracle cuts refund-to-revocation latency to seconds. Missing, expired, tampered, or corrupt license files just show the free label — tool availability is never affected.

Back-compat: SASSYMCP_LICENSE_BYPASS=1 (the old dev escape hatch that unlocked gated groups) is accepted and ignored — there is nothing left to bypass.

Running supervised (sassymcp supervise)

For always-on / remote deployments, run SassyMCP under its built-in supervisor instead of bare launcher scripts:

sassymcp.exe supervise start              # bridge only (127.0.0.1:21001)
sassymcp.exe supervise start --tunnel-mode managed   # also run the cloudflared tunnel as a child
sassymcp.exe supervise status             # JSON status; exit code != 0 if unhealthy
sassymcp.exe supervise stop               # graceful stop

The supervisor owns the runtime tree and makes it self-healing and orphan-proof:

• No orphans, ever. A hard kill of the supervisor (crash, kill -9, taskkill /f) takes every child with it — on Windows via a Job Object (KILL_ON_JOB_CLOSE), on Linux via process groups + PR_SET_PDEATHSIG. No leftover bridge holding a wedged SQLite/WAL lock, which is what the old taskkill-based scripts caused.
• Self-healing. Crashed children restart with exponential backoff (and give up cleanly after a crash-loop, rather than spinning).
• Catches hangs. An HTTP readiness probe recycles a hung-but-alive bridge — the failure a Windows scheduled task can never detect.
• Crash-survivable control. A pidfile + on-disk registry under $SASSYMCP_HOME mean supervise status/stop work even when the bridge is down, so an operator or agent can recover a wedged system.

start-supervised.bat wraps this as the recommended Windows launcher. stdio mode (Claude Desktop pipe) is client-owned and intentionally not supervised.

Modules

Counts generated from the registered tool set (278 tools across 39 modules, 18 groups; the prompts group exposes MCP prompts rather than tools).

Full per-tool reference (generated): docs/TOOLS.md.

iPhone support (experimental)

SassyMCP can talk to iPhones over USB via libimobiledevice. This is new in v1.16.0 and experimental — Android-over-ADB remains the mature path.

Prerequisites

• Install libimobiledevice: brew install libimobiledevice (macOS) or sudo apt install libimobiledevice-utils (Linux). Windows hosts have limited support — use WSL2 or a macOS/Linux host.
• Pair the device once: run idevicepair pair and tap Trust on the iPhone. iOS 17+ requires this pairing step before any tool will see the device.
• If several iPhones are connected, pass the udid parameter (from sassy_iphone_list) to target one.

Tools: sassy_iphone_list, sassy_iphone_info, sassy_iphone_screenshot, sassy_iphone_syslog (bounded capture), sassy_iphone_apps, sassy_iphone_install (requires confirm='YES'). Every tool degrades gracefully when the binaries or a trusted device are missing — you'll get an install hint or a pairing reminder, never a traceback.

Dynamic Vision

Desktop (Vision module)

Traditional MCP screenshots are blind — you capture one frame and hope it's the right one. SassyMCP's dynamic vision changes this:

All three use grayscale + heavy JPEG compression to keep context cost minimal. A glance is ~2KB vs ~14KB for a full-color capture.

Android (PhoneScreen module)

The phone isn't just a camera target — SassyMCP reads its UI accessibility tree:

Phone Interaction

Full touch input via ADB — the AI can operate the phone:

Sensitive Context Detection

All interaction tools (tap, swipe, type) automatically scan the UI tree before executing. If they detect login screens, payment forms, account selectors, 2FA prompts, or permission dialogs, the tool refuses to execute and returns what it sees instead. The AI then describes the screen to you and asks what to do. Pass confirmed=True after explicit user approval.

Safe Delete (Delete Interception)

AI agents can hallucinate destructive commands. SassyMCP intercepts all delete-family commands across every shell and every tool entry point, then moves targets to a _DELETE_/ staging folder instead of destroying them. Every interception is written to the audit log with the raw command, parsed targets, and move results.

Coverage — every destructive path is gated:

Intercepted command keywords: rm, rmdir, unlink (Unix/WSL), del, erase, rd (CMD), Remove-Item, ri, rni (PowerShell aliases), sdelete / sdelete64 (Sysinternals).

Also caught (beyond bare keywords):

• Shell wrappers — powershell -c "del foo", cmd /c del foo, bash -c "rm foo", wsl -- rm foo (payload is recursively scanned)
• Base64 payloads — powershell -EncodedCommand <base64> is decoded (UTF-16-LE) and recursively scanned
• .NET calls — [System.IO.File]::Delete(...), [System.IO.Directory]::Delete(...)
• Clear-Content, Set-Content -Value '' (literal empty only — normal -Value "foo" is allowed)
• Out-File -Force, New-Item -Force (overwrite-style)
• copy /y, xcopy /y — CMD silent-overwrite flags
• robocopy /MIR and robocopy /PURGE — mirror/purge modes delete destination files
• Truncate-by-redirect — > file.txt, type foo > bar.txt, cmd; > file.txt (append >> and stream 2> / &> correctly ignored)
• Move-Item foo $null
• Assignment prefixes — $null = ri foo is correctly unwrapped

Protected roots (refused by every guarded tool, not just the interceptor): the SassyMCP source tree itself, ~/.sassymcp/ (audit + config), and any _DELETE_/ staging folder (no staging recursion). Protection uses resolve() so path traversal (..\), symlinks, and Windows 8.3 short names all normalize correctly before the check.

Name collisions in _DELETE_/ are handled automatically with counter suffixes (file.txt, file_1.txt, file_2.txt). On Windows, paths with backslashes (C:\Users\foo\bar) are preserved correctly by the parser — no shlex mangling.

Pause / Resume

For complex flows where the user needs to take over:

Workflow:

1. AI operates phone autonomously for routine tasks
2. AI hits a login screen → sensitive context auto-blocks → AI tells the user
3. User says "hold on" → AI calls sassy_phone_pause
4. User logs in manually. AI watches via sassy_phone_ui / sassy_phone_glance
5. User says "done" → AI calls sassy_phone_resume
6. AI continues, now aware the user logged into a specific account

Permission Engine & Control Panel

SassyMCP gates the shell and file tools through one policy engine (sassymcp.policy) with four modes, set via sassy_permission set_mode or the Control Panel:

A Claude-style allow / ask / deny rules layer (tool-glob + path-glob + command-regex; first match wins) overrides the mode default. The catastrophic block-list (format, mkfs, …) and the protected-path invariant (the SassyMCP source tree + ~/.sassymcp) hold in every mode, including bypass.

The Control Panel is a localhost web UI for all of the above — a live event log, the settings/mode editor, and a classifier + rules editor. It binds 127.0.0.1 only and needs the per-install token in ~/.sassymcp/control_panel.token. Start it with sassy_panel start (or set panel.enabled / SASSYMCP_PANEL=1 to launch it at boot), then open the printed http://127.0.0.1:8765/?token=… URL.

Tool profiles

Tool profiles gate which tools an MCP session can see (tools/list) and call (tools/call) — a per-session, human-controlled subset of the catalog, managed from the Control Panel (a Profiles tab, backed by GET/POST /api/profile). There is deliberately no MCP tool that can switch or widen the profile, so a session can never escalate itself out of a restrictive profile; fan-out through sassy_batch respects the same gate.

Rules worth knowing:

• Session-scoped, never persisted. A restart always comes back up on full. Profiles are a runtime seatbelt, not access control — the panel token is the trust boundary.
• meta stays on. Its introspection tools (sassy_tool_groups, sassy_self_check, …) are the session's only window into what it can see; hiding them would strand the session with no way to inspect the gate.
• Widening needs confirm='YES'. Any switch that would expose a currently-hidden tool is an audited escalation and requires explicit confirmation (the panel UI sends it for you, mirroring the bypass-mode convention). Narrowing never does.
• A tool hidden from tools/list is also uncallable via tools/call — a client cannot call what it cannot see.

Guided Setup

On first launch (no ~/.sassymcp/persona.md), the wizard tools are prominently available and the AI is given an onboarding playbook via the registered hook. The flow is conversational — the AI asks, you answer, it calls the tools.

Onboarding procedure (recommended order)

Each step is independent and skippable. Just tell the AI "set up SassyMCP" or "let's get started" and it'll walk this:

Skip any step with action="skip" (where supported) — config records the skip so the AI doesn't re-prompt.

The persona questionnaire

sassy_setup_wizard accepts these fields. All optional — defaults shown.

Output goes to ~/.sassymcp/persona.md (the persona module reads it on every session) and the run is recorded in ~/.sassymcp/config.json (setup_complete, setup_timestamp, setup_version). Re-run sassy_setup_wizard any time to regenerate — the persona module hot-reloads with the new profile.

Triggering the flow from your client

The onboarding hook fires on phrases like "setup", "first time", "get started", "onboard", "new user", "set up sassymcp". Anything close to those will pull the playbook into the AI's context. If you want to drive it manually, just call sassy_setup_status first to see where you are, then walk the table above.

Smart Loading

By default, SassyMCP only loads frequently-used tool groups. This keeps tool definitions under 5% of your context window.

# Default: loads core, github_quick, persona, meta, utility, setup, infrastructure
uv run sassymcp

# Load everything (~22K tokens of context)
SASSYMCP_LOAD_ALL=1 uv run sassymcp

# Load specific groups
SASSYMCP_GROUPS=core,github_quick,android,v020 uv run sassymcp

Available Groups

Install

Pick whichever entry point matches how you already work. All four converge on the same shared brain at ~/.sassymcp/ — your persona, memory, license, and audit log are visible to every connected MCP client.

One-click via DXT (Claude Desktop)

Download sassymcp.dxt from the latest release, double-click — Claude Desktop installs it. On first launch, sassymcp auto-detects every other MCP client on your machine (Cursor, VS Code Copilot, Windsurf, Continue, Cline, Zed, Grok Desktop) and patches each one's config so they all see SassyMCP without you editing any JSON.

VS Code extension

Install the VS Code extension from the .vsix attached to the latest release until the Visual Studio Marketplace listing is live. The extension locates sassymcp.exe (PATH or the sassymcp.exePath setting), runs the same auto-config CLI, and adds a status bar item showing supporter-tier label and brain health. Command palette: Open Sassy Brain Cockpit, Run Setup Wizard, Reinstall Client Configs, Open Audit Log, Open _DELETE_ Folder, Show Brain Status.

Manual auto-config CLI

If you have sassymcp.exe already (from the portable zip or pip install) and want to register it with every MCP client without per-client JSON editing:

sassymcp-install

That detects Claude Desktop, VS Code Copilot, Cursor, Windsurf, Continue, Cline, Zed, and Grok Desktop and patches each one's config atomically. Re-running is a noop. Take a look first with sassymcp-install --dry-run. Remove with sassymcp-install --uninstall. The CLI takes a timestamped backup of any existing config before its first edit.

Portable bundle

The portable zip (sassymcp-v*-portable.zip with bundled adb, nmap, plink, scrcpy, tesseract, cloudflared, and the start-*.bat launchers) is no longer published — the release pipeline does not build it. Use the standalone executable below (and install any helper tools you need on PATH), or pip install sassymcp for the full Python install.

Standalone executable (no tools bundled)

If you don't need the bundled nmap / adb / cloudflared (or you have them on PATH already), grab just sassymcp.exe (~35 MB) from the latest release. Drop it anywhere and point your MCP client at it.

First-run wizard: Double-click sassymcp.exe (or run it from a terminal with no flags) on a fresh machine and you'll get an interactive menu — auto-detect AI agents and register SassyMCP, activate a LemonSqueezy license key, generate / list bearer tokens, or start the HTTP server. Run sassymcp.exe setup anytime to re-open the menu. Once a persona is configured, bare invocation falls back to starting the HTTP server (the v1.5 behavior) so existing setups are unchanged.

Linux (pip only)

CI publishes no Linux binary. On Linux, install the wheel: pip install sassymcp. (The standalone executable is Windows-only; macOS ships a universal2 binary — see sassymcp-macos on the release page.)

MSI installer (manual builds only)

No MSI is published by CI — build-msi.ps1 exists for manual MSI builds (WiX 3.x) from a staged sassymcp.exe, and installer.wxs is a manual-build reference template, not a maintained installer.

Activating a supporter license (optional)

There is no separate "licensed download" and nothing to unlock — everyone runs the same fully-unlocked binary from the GitHub releases. If you want to support development, buy a license at sassyconsultingllc.com/store and activate it to register your seat and supporter tier:

# from your AI agent:
sassy_setup_license action=activate key=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
# or from a terminal — interactive menu, choose "Activate license":
sassymcp.exe setup

The license registers this machine as a LemonSqueezy instance (seat); sassy_setup_license action=deactivate frees the seat to move to another machine.

From source

git clone https://github.com/sassyconsultingllc/SassyMCP.git
cd SassyMCP
uv sync

# Optional dependencies:
uv pip install pytesseract playwright
playwright install chromium

Cloudflare Tunnel (remote access)

Want to drive SassyMCP from a remote MCP client (Claude Web, another machine)? The portable bundle ships a turnkey launcher. Full step-by-step is in docs/TUNNEL.md; the short version:

winget install Cloudflare.cloudflared          # one-time
cloudflared tunnel login                       # authenticate against your CF account
cloudflared tunnel create sassymcp             # create a named tunnel
cloudflared tunnel route dns sassymcp mcp.<your-domain>.tld
# Write ~/.cloudflared/config.yml with the ingress block (see TUNNEL.md)

[Environment]::SetEnvironmentVariable("SASSYMCP_AUTH_TOKEN", "<your token>", "User")
[Environment]::SetEnvironmentVariable(
    "SASSYMCP_ALLOWED_HOSTS",
    "mcp.<your-domain>.tld,localhost,127.0.0.1", "User")

cd D:\Tools\SassyMCP                           # wherever you extracted
.\start-tunnel.bat sassymcp                    # tunnel name as arg, or set SASSYMCP_TUNNEL_NAME

start-tunnel.bat launches the HTTP bridge on 127.0.0.1:21001 and runs cloudflared tunnel run <name> in the foreground. Nothing in the script is vendor-specific — you supply the tunnel name and the hostname. Clients send Authorization: Bearer <SASSYMCP_AUTH_TOKEN> against https://mcp.<your-domain>.tld/mcp.

For hosted-Claude clients that require OAuth 2.1 DCR/PKCE instead of a static bearer, deploy the optional Worker under sassymcp-oauth/ — copy wrangler.toml.example to wrangler.toml, fill in your hostname and KV id, and wrangler deploy. See docs/TUNNEL.md for the full OAuth section.

MCP Client Config

SassyMCP speaks standard MCP. Anything that connects works — no client-side modifications required. The portable bundle ships ready-to-edit templates under deploy/*_config.template.json. Pick the row for your client, copy the template, replace REPLACE_WITH_PATH with the absolute path to sassymcp.exe, and save it where the client expects.

Standard mcpServers shape (Claude Desktop, Cursor, Windsurf, Cline)

Using the exe:

{
  "mcpServers": {
    "sassymcp": {
      "command": "C:\\path\\to\\sassymcp.exe",
      "env": {
        "SASSYMCP_LOAD_ALL": "1",
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

From source:

{
  "mcpServers": {
    "sassymcp": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\SassyMCP", "run", "sassymcp"],
      "env": {
        "SASSYMCP_LOAD_ALL": "1",
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Continue.dev shape (different schema)

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "C:\\path\\to\\sassymcp.exe"
        }
      }
    ]
  }
}

HTTP / Grok Desktop / custom HTTP clients

Run the server in HTTP mode (sassymcp.exe --http, default 127.0.0.1:21001) and point your client at http://127.0.0.1:21001/mcp/. Set SASSYMCP_AUTH_TOKEN if the bind is non-loopback.

{
  "mcpServers": {
    "sassymcp": {
      "url": "http://127.0.0.1:21001/mcp/"
    }
  }
}

What's actually Claude-flavored (cosmetic only)

A few docstrings and the legacy .claude/skills/sassymcp-update.md slash-command target Claude Code specifically. Other clients ignore them and use sassy_update_* tools directly. No tool, transport, or auth path requires Claude — the server doesn't know which LLM is on the other end.

Transport Modes

Running Multiple Instances (Dual Session)

Two SassyMCP processes on the same machine — for example, a local stdio instance for Claude Desktop and a remote HTTPS instance behind a Cloudflare Tunnel for Claude Web — can clobber each other's state if they share ~/.sassymcp/. The fix is one env var per instance.

Conflicts to resolve per-instance

Example: local stdio + remote tunnel side-by-side

Instance A — local stdio for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "sassymcp-local": {
      "command": "C:\\Tools\\SassyMCP\\sassymcp.exe",
      "env": {
        "SASSYMCP_LOAD_ALL": "1",
        "SASSYMCP_HOME": "C:\\Users\\<you>\\.sassymcp-local"
      }
    }
  }
}

Instance B — remote HTTPS via Cloudflare Tunnel (start-tunnel.bat + a wrapper that sets the env):

set SASSYMCP_HOME=C:\Users\<you>\.sassymcp-remote
set SASSYMCP_AUTH_TOKEN=<token-for-remote>
set PORT=21002
"%~dp0sassymcp.exe" --http --host 127.0.0.1 --port %PORT%

Then cloudflared tunnel run <name> forwards https://<your-tunnel>/mcp to 127.0.0.1:21002.

What's isolated when SASSYMCP_HOME differs

Each instance gets its own:

• persona.md — different profiles per session
• config.json — different runtime config (allowed dirs, blocked commands, etc.)
• tokens.json — different scoped auth tokens
• license.json — separate license activation
• audit.log / audit.jsonl — no interleaved writes
• crosslink.db — separate cross-session message queues
• memory.db — separate persistent memories
• tool_state.db / tool_usage.json — separate per-tool state and usage analytics
• server.crt / server.key — separate self-signed certs
• The _security protected-paths check honors SASSYMCP_HOME too — neither instance can sassy_safe_delete into the other's home

What's still shared between instances

• The repo source tree (always protected from delete/overwrite by _security)
• %LOCALAPPDATA%\SassyMCP\updates\ — the updater download stage (harmless; tagged by version under it)
• The bundled tools in the portable zip (adb, nmap, cloudflared, etc.) — read-only from both instances

Putting it in the OS (so both start at boot)

The legacy personal/autostart-bridge.bat + personal/register-autostart.ps1 template is gitignored — copy it, tweak the paths and the SASSYMCP_HOME for each instance, then Register-ScheduledTask once per instance.

Environment Variables

External Tools

All bundled in the beta zip package. Install separately only if using the standalone exe.

Run sassy_setup_check_tools to verify all tools are detected.

Requirements

• Windows 10/11, macOS 12+, or Linux — one source, routed at the head (sassymcp._platform) to the right command per host. See Cross-platform below.
• Python 3.11+ (only if running from source; the standalone binary is self-contained — built per OS, since PyInstaller can't cross-compile)

Cross-platform

The same SassyMCP source runs on Windows, macOS, and Linux. The host OS is resolved once at import; every tool then routes to the host-appropriate command — shells (PowerShell / zsh|bash), clipboard (Get-Clipboard / pbpaste), event log (Get-WinEvent / log show / journald), firewall (netsh / socketfilterfw / ufw), Wi-Fi, Bluetooth, window control (pywinauto / AppleScript System Events / wmctrl), SSH (plink / native ssh), package installs (winget / brew / apt), and more.

• Build: build.bat (Windows) or build.sh (macOS/Linux). Build each binary on its own OS.
• macOS permissions: window-control and screenshot tools need Accessibility and Screen Recording permission for the app running SassyMCP (System Settings → Privacy & Security).
• A handful of concepts are Windows-only by nature (raw Registry read/write/export); those report a clear message and point to the native equivalent (defaults, launchd). Forensic persistence (sassy_autorun_entries) IS cross-platform (Run keys / LaunchAgents / systemd+cron).

License

Proprietary - Copyright (c) 2026 Sassy Consulting LLC. All rights reserved.