EdgeDefense

Ask Claude about your home network.Runs on your machine — no account, no admin rights, and nothing sent anywhere except the one speed test you have to ask for.

Server-specific docs live inmcp-server/README.md.

pip install "edgedefense-core @ git+https://github.com/splashxmoon/edgemcp.git#subdirectory=core-engine" "edgedefense-mcp @ git+https://github.com/splashxmoon/edgemcp.git#subdirectory=mcp-server"

claude mcp add edgedefense -- edgedefense-mcp

codex mcp add edgedefense -- edgedefense-mcp

{ "mcpServers": { "edgedefense": { "command": "edgedefense-mcp" } } }

{ "mcpServers": { "edgedefense": { "command": "edgedefense-mcp" } } }

[mcp_servers.edgedefense] command = "edgedefense-mcp" args = []

{ "servers": { "edgedefense": { "command": "edgedefense-mcp" } } }

Restart your client afterwards. Any other MCP client works too — the command isedgedefense-mcp, it takes no arguments, and it speaks stdio.

Remote connector (claude.ai "Add custom connector")

That dialog asks for a URL rather than a command, which means the server has to be reachable over HTTP.

The server must still run on a machine in your home.It identifies devices by reading the local address table and listening for the announcements devices broadcast on the local link — so it can only ever see the network it is sitting on. Hosting it on a VPS would work perfectly and tell you about the VPS's network, which is not what you want. The arrangement that makes sense is a tunnel from a public hostname back to a machine at home.

Keeping it running, and shipping updates without breaking the URL

Once other people are using the URL, two things about the simple setup start to hurt:
- A quick tunnel's hostname is random, and changes on every restart.
- serve_remote.pystops the tunnel when it stops the server, so restarting to pick up new code silently hands you a different address.

Together those mean a routine deploy breaks every saved connector URL — and it breaks quietly, because the old address just stops answering.

scripts/serve_forever.pyis the supervised version that avoids both:

python scripts/serve_forever.py --hostname mcp-tunnel.example.com

It starts the tunnelonceand leaves it alone. Every five minutes it fetches the tracked branch, and when new commits land it fast-forwards and restartsonly the server. The tunnel keeps running throughout, so the public address — and every URL anyone has saved — survives the update. Push tomain, and within five minutes the remote server is serving the new code at the same link.

- --ff-only.A supervisor that silently creates merge commits on an unattended machine is a way to lose work. A diverged branch is reported and the current code keeps serving.
- The tunnel is restarted only if it actually dies.Restarting a healthy tunnel is the one thing guaranteed to break the URL.
- --check-every 0disables auto-updating if you would rather deploy by hand.

Without--hostnameit falls back to a quick tunnel and prints a warning: the address is then only stable for as long as that tunnel process lives.

Start with a quick tunnel. It needs no DNS changes at all and proves the whole thing works in about a minute:

cloudflared tunnel --url http://127.0.0.1:8765

That prints ahttps://<random>.trycloudflare.comURL. Pass it as--public-urland use it in your client. The URL changes each run, which is fine for testing.

For a stable address on your own domain, note two things. A subdomain likemcp.example.comis yours automatically — subdomains are not bought separately, you just create a DNS record. Butcloudflared tunnel route dnsonly works if the domain's nameservers point at Cloudflare. If your domain is still on your registrar's nameservers, either move the zone to Cloudflare (re-creating every existing record first —MX records especially, or email stops arriving) or use a tunnel provider that gives you a CNAME target you can paste into your current DNS panel.

Connecting opens a sign-in page on your own domain, and your client ends up holding a revocable token instead of a secret URL. The authorization server runs inside this process — there is no hosted login service and no account.

export EDGEDEFENSE_PASSPHRASE='choose-something-long' edgedefense-mcp --http --oauth --public-url https://mcp.edgedefenseai.com --port 8765

cloudflared tunnel --url http://127.0.0.1:8765

Then paste just the endpoint into the connector dialog, leaving both OAuth fields empty:

The client registers itself, discovers the authorization server, and opens the sign-in page. Enter the passphrase and it connects. Restarting the server revokes every issued token.

--public-urlmust match exactly what the browser sees, since the OAuth metadata and the redirect back to your client are built from it.

Create an OAuth client in the Google Cloud Console (APIs & Services → Credentials → Create credentials → OAuth client ID → Web application), and add this exact redirect URI:

https://mcp.edgedefenseai.com/auth/google/callback

export EDGEDEFENSE_GOOGLE_CLIENT_ID='...apps.googleusercontent.com' export EDGEDEFENSE_GOOGLE_CLIENT_SECRET='...' edgedefense-mcp --http --oauth \ --public-url https://mcp.edgedefenseai.com \ --allow-email you@gmail.com \ --no-passphrase

--allow-emailis required and repeatable. Signing in with Google proves who someone is; it does not decide whether they may read your network, and without an allowlist any Google account would satisfy the check. Omit--no-passphraseto offer both methods on the sign-in page.

One honest caveat.With Google sign-in enabled, this server contacts Google while somebody is signing in — that is unavoidable for any identity provider. Scanning still makes no outbound request of any kind, and no network data is ever sent anywhere. If you would rather the server never talk to anything, use the passphrase — and leaveedgedefense_speed_testalone, which is the only other tool that reaches outside your machine.

No browser step; the secret lives in the URL instead.

edgedefense-mcp --http --port 8765 --token "$(python -c 'import secrets;print(secrets.token_urlsafe(32))')" --allow-host mcp.edgedefenseai.com

cloudflared tunnel --url http://127.0.0.1:8765

Then paste the printed endpoint into the connector dialog:

https://mcp.edgedefenseai.com/t/<your-token>/mcp

Leave the OAuth fields empty. The dialog has nowhere to put a header, so the token travels in the path instead.

The URL is a password.Anyone holding it gets a full inventory of your home network. Don't put it anywhere you wouldn't put a password, and rotate it by restarting with a new--token.

Binding to anything other than loopback without a token is refused; the server generates one and prints it rather than exposing your network anonymously.--allow-hostmust name the hostname clients will actually use, or the DNS-rebinding check rejects the request.edgedefense-mcp --helplists the rest.

Desktop apps often don't see the samePATHyour terminal does, which matters if you installed into a virtual environment. Find the real location:

# macOS / Linux which edgedefense-mcp # Windows where edgedefense-mcp

Then use that full path in the config instead of the bare name:

{ "mcpServers": { "edgedefense": { "command": "/full/path/to/edgedefense-mcp" } } }

Running it through Python directly also works, and avoids thePATHquestion entirely:

{ "mcpServers": { "edgedefense": { "command": "/full/path/to/python", "args": ["-m", "edgedefense_mcp"] } } }

Scan my home network and tell me what's connected.

What's my network trust score, and why?

Is anything unusual connected right now?

Good follow-ups once you have results:"What is that device at 192.168.1.47?"·"Which devices couldn't you identify?"·"Why is that a problem?"

Below this line is for people reading the code rather than using the tool.

This is a monorepo with a deliberate split between shared detection logic and the products built on top of it.

edgemcp/ ├── core-engine/ Shared discovery, identification and scoring. Imported, never forked. ├── mcp-server/ The free, open-source MCP server. Ships independently. └── core-app/ The paid Core/Home product. Not present yet.

core-engine/is the only place detection logic lives. Bothmcp-server/and the futurecore-app/import it the same way; neither reimplements any of it.

This is decided up front on purpose. Retrofitting a shared engine after two codebases have already diverged is expensive and entirely avoidable, and the cheapest moment to draw the line is before the second consumer exists.

mcp-server/is a separate folder rather than a subfolder of the engine because it ships independently: its own packaging, its own public repository, its own README, its own MIT licence.

mcp-server/is public. Anything reachable from it is public.

core-engine/therefore contains only generic, safe-to-open-source logic: device discovery, ARP and mDNS scanning, vendor lookup, and scoring arithmetic.