Ask AI assistants like Claude directly about your Mac / Linux security status
RoamSwitch bundles a read-only MCP (Model Context Protocol) server. Connect it to an MCP client and just ask, in plain language, "is my Mac / Linux machine secure right now?" or "what ports are exposed?" โ you'll get answers grounded in RoamSwitch's own accurate diagnostics, not guesswork. It can't switch lockdown levels, isolate ports, or perform any other action; all communication stays entirely on-device over stdio (an extension of our Zero Telemetry policy).
๐ Why it's safe
- Read-only: Only security diagnostics, port monitoring, and guard-setting checks. No operational tools like switching lockdown, isolating ports, or ejecting devices are implemented.
- Fully local: Communication is stdio only. It stays entirely between your AI client (Claude Desktop/Code, etc.) and the RoamSwitch process on your Mac / Linux machine โ nothing is ever sent to an external server.
- No accidental changes: Since there are no operational tools, there's no risk of a prompt injection or similar accidentally changing your firewall or network settings.
Set up in two steps
1Binary location
Bundled with RoamSwitch.app โ no separate download or installation needed.
/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
2aFor Claude Desktop
Add the following to "mcpServers" in ~/Library/Application Support/Claude/claude_desktop_config.json, then restart Claude Desktop.
{
"mcpServers": {
"roamswitch": {
"command": "/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"
}
}
}
2bFor Claude Code
Just run the following command once in your terminal.
claude mcp add roamswitch /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
2cFor OpenAI Codex CLI
Add the following to ~/.codex/config.toml, or run the command below in your terminal.
[mcp_servers.roamswitch] command = "/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"
codex mcp add roamswitch -- /Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer
2dFor OpenCode
Add the following to opencode.json in your project root (or global config ~/.config/opencode/opencode.json).
{
"mcp": {
"roamswitch": {
"type": "local",
"command": ["/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"]
}
}
}
๐ก Local LLM Support: When paired with local models via Ollama or LM Studio, you can query RoamSwitch for safety checks and advice completely offlineโeven while RoamSwitch has severed external network access due to active threat containment.
2eFor Antigravity
Add the following to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json at your workspace root).
{
"mcpServers": {
"roamswitch": {
"command": "/Applications/RoamSwitch.app/Contents/MacOS/RoamSwitchMCPServer"
}
}
}
* Note: If you encounter Hook Failure or telemetry errors in Antigravity CLI (agy), disable the hook by setting "enabled": false in ~/.gemini/config/plugins/.../hooks.json.
1Binary location
Bundled in the apt / rpm / AUR package and installed automatically at /usr/bin/roamswitch-mcp. No separate download or build is needed (same for the Client and Server Edition).
/usr/bin/roamswitch-mcp
The same binary and setup steps work as-is on Server Edition (headless). See the "AI Agents / MCP Integration" chapter of the Linux Server operations manual for details.
2aFor Claude Desktop
Claude Desktop has no official Linux release. If you're using an unofficial build (e.g. claude-desktop-debian), add the following to "mcpServers" in ~/.config/Claude/claude_desktop_config.json and restart it.
{
"mcpServers": {
"roamswitch": {
"command": "/usr/bin/roamswitch-mcp"
}
}
}
2bFor Claude Code
Just run the following command once in your terminal.
claude mcp add roamswitch /usr/bin/roamswitch-mcp
2cFor OpenAI Codex CLI
Add the following to ~/.codex/config.toml, or run the command below in your terminal.
[mcp_servers.roamswitch] command = "/usr/bin/roamswitch-mcp"
codex mcp add roamswitch -- /usr/bin/roamswitch-mcp
2dFor OpenCode
Add the following to opencode.json in your project root (or global config ~/.config/opencode/opencode.json).
{
"mcp": {
"roamswitch": {
"type": "local",
"command": ["/usr/bin/roamswitch-mcp"]
}
}
}
๐ก Local LLM Support: When paired with local models via Ollama or LM Studio, you can query RoamSwitch for safety checks and advice completely offlineโeven while RoamSwitch has severed external network access due to active threat containment.
2eFor Antigravity
Add the following to ~/.gemini/config/mcp_config.json (or .agents/mcp_config.json at your workspace root).
{
"mcpServers": {
"roamswitch": {
"command": "/usr/bin/roamswitch-mcp"
}
}
}
* Note: If you encounter Hook Failure or telemetry errors in Antigravity CLI (agy), disable the hook by setting "enabled": false in ~/.gemini/config/plugins/.../hooks.json.
Read-only tools (currently 17 on Mac / 25 on Linux โ growing)
get_security_report
Runs an 18-point audit on Mac (FileVault, SIP, Gatekeeper, firewall, Wi-Fi encryption strength, ARP spoofing, exposed ports, etc.) or a 24-point client / 30-point server audit on Linux (kernel hardening, Docker socket and privileged-container protection, container runtime isolation, known vulnerabilities, etc.), and returns a score with improvement advice.
get_exposed_ports
Lists every port currently listening and, for any exposed externally, returns a detailed audit including known-risky-service detection (Redis, MongoDB, etc.).
get_guard_status
Returns active status of unknown port guard, ARP containment, USB guard, Bluetooth guard, Web/Mail download guard, DNS threat guard, and current security level.
audit_url_safety
Takes an email link or web URL to analyze phishing threats, Unicode homograph spoofing, deceptive subdomains, redirect chains, and high-risk TLDs completely on-device (Zero Telemetry).
get_app_help
Searches RoamSwitch's complete authoritative knowledge base covering all feature specifications, alert messages, settings, and troubleshooting on-device to return precise explanations and actionable advice.
audit_security_logs
Aggregates recent security logs (Mac: sudo auth failures, SSH brute-force attempts, Gatekeeper blocks, XProtect detections, etc. / Linux: sudo auth failures, SSH brute-force, firewall drops, AppArmor denials, ClamAV detections, etc.), automatically masks secrets like API keys and tokens, and also returns new-pattern detection (log templating) and frequency-anomaly (statistical spike) results.
get_notification_history
Returns the history of notifications RoamSwitch has sent (security log-audit anomalies, ClickFix detections, and the like) from the past 7 days, most recent first.
roamswitch://docs/* (MCP Resources)
Official documentation resources that AI clients can read directly into context (features, alert advice, settings, troubleshooting).
Other read-only tools
| Tool | Platform | Summary |
|---|---|---|
audit_secrets |
Mac / Linux | Detects leaked API keys and private keys in text, a file, or a directory tree (matches are masked in the output). |
run_active_vuln_scan |
Mac / Linux | Non-destructive, 127.0.0.1-only active vulnerability verification. The only tool that uses the network; off by default and requires opting in from Settings. |
run_package_cve_scan |
Mac / Linux | Checks installed packages (Mac: Homebrew / Linux: dpkg, dnf, zypper, pacman) against a local CVE map. Sends no network traffic at all. |
run_package_cve_scan_languages |
Mac / Linux | Checks dependency lockfiles for npm, PyPI, crates.io, RubyGems, Packagist, Go, and Maven against the same local CVE map. Sends no network traffic at all. |
get_quarantine_status |
Mac / Linux | Returns the malware quarantine vault's contents: original path, detected threat name, quarantine time and size. |
get_canary_status |
Mac / Linux | Returns the ransomware canary's decoy-file state plus up to the 50 most recent detected incidents. |
get_port_anomaly_incidents |
Mac / Linux | Returns the Port Anomaly Guard's baseline state, currently auto-blocked ports, and up to the 50 most recent incidents. The response explicitly notes that the currently-blocked ports are a present-tense snapshot with no timestamp, distinct from the timestamped incident history. |
get_runtime_threat_status |
Mac | Returns whether an XProtect malware conviction has air-gapped this Mac, and the incident that triggered it. Check this first to explain an active Air-Gap. |
verify_fim |
Linux | Re-hashes about 150 critical system files and compares them against the stored baseline to verify integrity. |
get_file_scan_guard_status |
Linux (Server) | Returns the File Scan Guard's (ClamAV) configuration and the state of the quarantine vault it feeds. |
get_ebpf_incidents |
Linux (Server) | Returns the eBPF Runtime Guard's current containment status and the incident history behind it. |
get_resource_guard_incidents |
Linux (Server) | Returns the Resource Exhaustion / Process Anomaly Guard's history (memory leaks, crash loops) with a confidence tier. |
get_incident_timeline |
Mac / Linux | Correlates every guard's detections into one chronological timeline, with process ancestry and MITRE ATT&CK tags (experimental). |
get_network_history |
Mac | Records how many distinct gateway devices have answered for each remembered Wi-Fi network and when it was last seen, and flags other networks with suspiciously similar names (Evil Twin candidates). Also answers whether you've connected to a given network before. |
get_vpn_status |
Linux (Client) | Returns whether VPN on untrusted networks (WireGuard / Tailscale) is enabled, whether the tunnel is actually up, and whether the leak-blocking kill switch is armed. |
get_link_guard_status |
Linux (Client) | Returns Link Guard's (phishing / malicious-site blocking via DNS / TLS SNI / HTTP Host inspection) enabled state, mode (off / warn / block), allowlist, and block/warn events from the last 7 days. |
get_air_gap_status |
Linux (Client) | Returns whether emergency Air-Gap isolation (all traffic dropped) is active right now, why it triggered, time until auto-release, and every process currently frozen with SIGSTOP. |
get_sharing_services_status |
Linux (Client) | Returns the setting that auto-stops SSH, Samba, and screen sharing (GNOME Remote Desktop / VNC / xrdp) on untrusted networks, and the live state of the services it actually stops and restores. |
get_bluetooth_guard_status |
Linux (Client) | Returns the Bluetooth Guard setting that force-disables discoverability on untrusted networks, and the controller's live state (powered, discoverable, connected devices). |
get_usb_guard_status |
Linux (Client) | Returns the USB storage guard and BadUSB keyboard guard settings (input is suppressed via evdev only โ devices are never de-authorized at the kernel level), plus connected and pending-approval devices. |
Of the tools above, the ones that only read local state (quarantine vault, canary, port anomaly, runtime threat, notification history, incident timeline, network history, VPN / Link Guard / Air-Gap / sharing services / Bluetooth / USB guard status, etc.) keep working even while RoamSwitch has cut network access in response to a threat. Paired with a local LLM, you can investigate the cause on the spot during a cutoff.
Real-World Prompts for Dev & Daily Workflows
Explore realistic prompts and AI responses for auditing dev server ports, checking public Wi-Fi security, verifying suspicious links, and more. Copy prompts directly into your AI.
Local Server & DB Port Exposure Audit
When launching Next.js, Vite, Python, Docker, Redis, etc., have your AI audit whether ports are inadvertently exposed to the local network on 0.0.0.0.
โข ๐จ Port 3000 (node / Next.js): Exposed externally on
0.0.0.0:3000โข ๐จ Port 6379 (redis-server): Exposed externally on
0.0.0.0:6379 (unauthenticated; accessible by other devices on same Wi-Fi)โข โ Port 5432 (postgres): Bound to
127.0.0.1:5432 (localhost only / safe)๐ก Remediation: Set
bind 127.0.0.1 in Redis configuration, and launch Next.js with npm run dev -- -H 127.0.0.1.Security Check on Public / Cafe Wi-Fi
Right after connecting to free Wi-Fi at a cafe or hotel, have AI perform a comprehensive posture check to verify if firewall, stealth mode, and ARP defense are active.
โข ๐ก๏ธ Overall Score: 88 / 100 (Grade: A-)
โข ๐ก Network Status: Untrusted Network (Public mode / packet filter active)
โข โ Firewall / Stealth Mode: Enabled (blocking external probe packets)
โข โ ARP Spoofing Auto-Containment: Enabled (auto-isolates on interception detection)
โข โ ๏ธ Action Item: FileVault disk encryption is disabled. Recommended to enable it in System Settings.
Inspecting Suspicious Email & Chat Links
Have AI instantly inspect URLs from suspicious emails or Slack/Discord DMs entirely on-device without sending the link to external servers (Zero Telemetry).
โข ๐จ Risk Level: Dangerous (Safety Score: 8/100)
โข โ Brand Spoofing Subdomain: Pretending to be
apple.com, but actual domain is login-auth-verify.xyz.โข โ High-Risk TLD:
.xyz is frequently associated with disposable phishing campaigns.โข ๐ Zero Telemetry: Inspected locally on your Mac with zero external data transmission.
โข ๐ Recommendation: Do not click the link. Delete and report the email immediately.
Autonomous Security Safeguard during Coding
When delegating fullstack tasks to Claude Code or Antigravity, let the agent use MCP tools as autonomous safeguards to verify that no unauthorized ports were opened.
1. Launched Fastify backend on port 8080.
2. ๐ RoamSwitch MCP Verification: Executed
get_exposed_ports and confirmed port is bound strictly to 127.0.0.1:8080 with no LAN exposure.3. Environment verified secure. Proceeding with integration tests.
Daily Security Check & Markdown Report Export
Generate a clean, structured Markdown security status report for IT compliance, company policy audits, or personal daily logs.
## ๐ก๏ธ Mac Security Health Report (2026-08-28)
- Score: 96 / 100 (Grade: A+)
- Core Defenses:
โข FileVault: โ
Enabled (APFS Encrypted)
โข SIP: โ
Enabled
โข Firewall / Stealth Mode: โ
Enabled
โข ARP Spoofing Auto-Containment: โ
Enabled
โข DNS Threat Guard: โ
Enabled (Quad9 Secure DNS)
- Action Items: None (Mac is in excellent security posture)Verifying USB, Bluetooth & Download Guards
Confirm active status for all RoamSwitch real-time guard features, including unknown USB storage alerts, Bluetooth monitoring, and download protection.
โข ๐ก๏ธ Active Level: Balanced (Standard Protection)
โข โ USB Storage Guard: Active (alerts/blocks unapproved USB connections)
โข โ Bluetooth Guard: Active (monitors proximity of unpaired devices)
โข โ Web/Mail Download Guard: Active (auto-scans quarantined files via ClamAV)
โข โ DNS Threat Guard: Active (blocks malicious C2 and phishing domains)
Ask About Features, App Usage, and Alert Messages
Consult the AI about any notification, warning, or fine-grained technical feature (PF packet filter, FSEvents, ClamAV quarantine, USB guard, etc.) and receive verified explanations from the built-in knowledge base.
โข ๐ช Reason: Your dev server launched on
0.0.0.0 (public to LAN). RoamSwitch blocked incoming external connections while preserving localhost.โข โ๏ธ Remediation:
1. Recommended (Localhost only): Launch with
npm run dev -- -H 127.0.0.1 to prevent exposing the port.2. LAN sharing: Whitelist port 3000 via RoamSwitch menu > 'Port Audit'.
โข ๐ Incident Analysis: A rogue host on the Wi-Fi was broadcasting spoofed ARP packets to impersonate the gateway and intercept/modify network traffic (Man-In-The-Middle attack).
โข ๐ก๏ธ Automated Defense: RoamSwitch's ARP containment triggered instantly, isolating the interface to prevent packet eavesdropping.
โข ๐ Recommended Action: Do not reconnect to that public Wi-Fi. Continue working securely on tethering. Review security logs under 'Log Audit'.
โข ๐ Reason for Ejection: Automatically unmounted to prevent unauthorized data exfiltration and BadUSB firmware attacks.
โข โ๏ธ Registration Steps: 1. Open RoamSwitch 'Settings' from the menu bar โ 2. Select 'USB Storage Guard' โ 3. Click 'Add from Connected Devices' and select your drive โ 4. Set permission to 'Read-Only (Recommended)' and save. It will mount safely on next connection.
โข โ ๏ธ Cause: XPC communication with the privileged background daemon
RoamSwitchHelper (which manages packet filtering) is temporarily disrupted.โข ๐ ๏ธ Recovery Steps:
1. Open Terminal and restart the helper daemon:
sudo killall RoamSwitchHelper2. Relaunch the RoamSwitch app.
3. In macOS 'System Settings' > 'General' > 'Login Items & Extensions', ensure
RoamSwitchHelper is enabled.Offline triage with a local LLM + MCP after an Air-Gap emergency lockdown
When Air-Gap (emergency network lockdown) triggers โ say, on ransomware detection โ it also cuts off cloud AI clients like Claude Desktop. But RoamSwitch's MCP server keeps working, since it only talks over a local process pipe; pair it with a local LLM (e.g. via Ollama) and you can keep diagnosing with zero network access. Log anomaly detection, tamper detection, and known-CVE matching are all fully local, so this is exactly the moment they're built for: when the network itself is gone.
โข ๐ Canary triggered: Encryption of
/var/www/decoy_invoice.pdf detected at 14:32:07; process suspicious_enc (PID 8823) was immediately frozen and isolatedโข ๐ Port monitoring (Port Anomaly Guard): No new auto-blocked listeners in the incident history โ the canary trigger appears to be the only entry point, with no additional backdoor ports opened
โข ๐ Log correlation (anomaly detection): A spike in
sshd auth failures starting 12 minutes before the trigger (frequency spike detected, Z-score 5.2) โ a possible entry pointโข ๐ Tamper detection (FIM): No tampering found across ~150 critical system paths โ no sign the breach reached the system layer
โข ๐ฆ Known-CVE check: Cross-referenced against the local CVE map โ no critical known vulnerabilities in the affected packages
๐ก Recommended action: The breach is likely confined to the web root. Before restoring from backup, individually check the other files in that directory as well.
About MCP integration
Q. Does it really never communicate externally?
A. Correct. The MCP server is a local process launched directly by your AI client over standard I/O (stdio), and contains no networking code whatsoever. Diagnostic results are computed on the spot, on this Mac / Linux machine.
Q. Can I use it without the Pro version?
A. Yes โ all tools work on the free version. However, whether each auto-guard is actually active also depends on Pro license status, so the tool can only confirm the toggle state in Settings.
Q. Which AI clients are supported?
A. Any client that supports the MCP (Model Context Protocol) stdio transport should generally work, even beyond the ones listed above. Verified with Claude Desktop, Claude Code, OpenAI Codex CLI, OpenCode, and Antigravity.
Q. Antigravity shows a "Hook Failure" or telemetry error when calling tools.
A. A PreToolUse hook from external plugins (such as Google Cloud telemetry) in Antigravity may block tool execution. Open ~/.gemini/config/plugins/.../hooks.json and set "enabled": false to disable the hook.
Q. Can I still query the MCP server when network access is severed?
A. Yes, if you are using a local LLM via tools like OpenCode (with Ollama or LM Studio), everything runs 100% on-device and queries work seamlessly even during emergency network air-gap containment. If you are using cloud LLMs (such as Claude API), switch to a safe connection like mobile tethering before querying.