Argus MCP server
Commit Nov 9, 2026Automates network source-of-truth reconciliation by discovering live network state and syncing it with NetBox via MCP tools.
Also known as freed-dev-llc/argus
- Stars
- 3
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- Apache-2.0
What is Argus MCP?
Argus automates network source-of-truth reconciliation by discovering live network state and syncing it with NetBox via MCP tools.
Summary generated from the project's README
About Argus MCP server
Network administrators and lab enthusiasts can use Argus to ensure their NetBox instance accurately reflects their actual hardware and connectivity. The server automates the process of discovering live network states, comparing them against the existing NetBox records, and reconciling any discrepancies. It functions as a bridge between physical infrastructure and your digital source of truth, supporting vendors like UniFi and pfSense/OPNsense through specialized vendor packs.
Users interact with the system via MCP-compliant coding agents like Claude Code or through a dedicated React dashboard. The setup requires a NetBox URL and an API token to function. When used through an MCP client, the server provides tools to list devices, perform discovery scans, view network topology, and generate drift reports. To prevent accidental changes, all write operations are dry-run by default and require manual confirmation before being applied to the NetBox database.
What you can do with it
- 1Audit network best practicesRun automated checks to see if your current network configuration follows established advisory rules.
- 2Synchronize NetBox with realityInstruct a coding agent to update NetBox IP addresses and device information based on recent discovery scans.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
NETBOX_TOKENNETBOX_URL
| Name | Description | |
|---|---|---|
| NETBOX_TOKEN | — | |
| NETBOX_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablefreed-dev-llc/argus is public and reachablegithub.com/freed-dev-llc/argus ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/freed-dev-llc/argus ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubArgus
The all-seeing keeper of your network's truth.
Argus is a home- and lab-network automation server built on NetBox. It treats NetBox as the single source of truth (SoT) for your network and works to keep that truth continuously reflecting reality — devices, IP addresses, prefixes, cabling, and topology — by discovering the live network, diffing it against NetBox, and reconciling the difference.
Argus exposes this capability to MCP-compliant coding agents (Claude Code, Codex, Kimi, …) as a set of tools, and ships a small React dashboard to query state, review drift, and trigger reconciliation by hand.
In Greek myth, Argus Panoptes was the hundred-eyed giant who never slept and saw everything. That's the job: always watching, always keeping the record true.
Status: v0.2.8+ — the full loop works end-to-end and is validated against live networks (UniFi + pfSense/OPNsense) + NetBox 4.6: discover (devices, clients, uplink topology) → diff → confirm → reconcile NetBox (DCIM + IPAM), surfaced via MCP tools, a React dashboard, and Ansible inventory. See docs/ROADMAP.md and CHANGELOG.md.
Part of the freed-dev-llc agent family — Argus is the open, shared network source-of-truth tool used by the family's private AI assistants and sibling tools. It pairs with Mnemosyne, the family's RAG knowledge brain, which explains the vendors Argus discovers — see the optional Ask the Brain integration.
How it fits together
Collectors (UniFi / pfSense-OPNsense / SNMP-LLDP / DHCP-ARP …) ─► normalize ─► diff vs NetBox ─► reconcile plan ─► apply
(server/src/argus/discovery/) (reconcile/) (dry-run default,
confirmation-gated)
NetBox ◄── pynetbox client ──► MCP tools (server/src/argus/tools/) ──► coding agents
└─► FastAPI (http_server.py) ──► React dashboard (web/)
NetBox is authoritative; Argus never invents truth — it makes NetBox match what it observes. Writes are dry-run by default and real changes are confirmation-gated. See docs/ARCHITECTURE.md and the Architecture Decision Records.
The HTTP server also keeps the record current on its own: it receives NetBox webhooks
(POST /webhooks/netbox, classify + structured-log) and can run an opt-in scheduled drift
loop (SCHEDULE_INTERVAL) that diffs on an interval — read-only — serving the latest result at
GET /api/drift/status and firing an optional alert webhook (ALERT_WEBHOOK_URL) on drift.
Optional bearer-token auth (HTTP_TOKEN) gates /api + /webhooks. See
server/README.md for setup and copy-pasteable examples.
Vendor packs. Discovery is a host/plugin layer
(ADR-0005): each vendor is a self-contained
VendorPack (a read-only collector + declarative metadata) discovered via an
argus.vendor_packs entry point, so packs can live out-of-tree and ship independently.
UniFi and pfSense/OPNsense ship in-tree; build your own from
argus-vendor-pack-template
(a GitHub “Use this template” repo). See docs/VENDOR_PACKS.md to
install or add packs.
Repository layout
| Path | What |
|---|---|
server/ |
Python MCP + FastAPI server (mcp, fastapi, pynetbox) |
web/ |
React + Vite + TypeScript dashboard |
docs/ |
Architecture, roadmap, and ADRs |
.github/ |
CI, Dependabot, issue/PR templates, CODEOWNERS |
Quickstart
Server
cd server
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Point Argus at your NetBox (see .env.example)
export NETBOX_URL="https://netbox.lan"
export NETBOX_TOKEN="<a NetBox API token>"
argus-http # FastAPI on :8080 (used by the web app)
argus-mcp # MCP server over stdio (used by coding agents)
argus-maint-mcp # separate maintenance MCP surface — release preview/verify (devtools; read-only)
If NETBOX_URL / NETBOX_TOKEN are unset, tools return a clear "NetBox not
configured" message rather than failing — handy for first-run exploration.
Web dashboard
cd web
npm install
npm run dev # http://localhost:5173 — proxies /api to the server on :8080
Use from a coding agent (MCP)
.mcp.json at the repo root registers the argus server. With the package installed
(pip install -e server), Claude Code (and other MCP clients) can call:
list_devices,get_device,list_prefixes,list_ip_addresses,search— read NetBoxlist_collectors,discovery_scan,network_topology— observe live network state + topologydrift_report,reconcile_apply— review and apply reconciliation (confirmation-gated)evaluate_practices— run a collector's best-practice rules for advisory findings (read-only)
Deployment
For a complete, self-contained environment (NetBox + its datastore + Argus server + web),
see deploy/: docker compose --env-file .env up -d --build brings up
a bundled NetBox (auto-provisioned with the API token Argus uses) plus the Argus server and
dashboard. Intended for validation and home/lab use. The
argus_deploy Ansible role automates the same steps
on a Docker host, and deploy/argus.service
keeps mesh-bound ports alive across reboots.
Published artifacts
Released v* tags publish to GHCR and PyPI:
-
Container images —
ghcr.io/freed-dev-llc/argus-serverandghcr.io/freed-dev-llc/argus-web(tags0.2.8andlatest):docker pull ghcr.io/freed-dev-llc/argus-server:0.2.8 docker pull ghcr.io/freed-dev-llc/argus-web:0.2.8 -
Python package — the server installs from PyPI as
argus-netbox(the import package staysargus; the console scripts areargus-mcp/argus-http):pip install argus-netbox argus-http # FastAPI server on :8080 · argus-mcp = MCP over stdio
Integrations
Argus is the inbound source-of-truth layer; outbound automation consumes NetBox:
- Ansible (
ansible/) — read-onlynb_inventorydynamic inventory sourced from the NetBox Argus keeps current; target hosts by site/role with no hand-maintained inventory. See ADR-0004 for how Argus, Ansible, and (future) Terraform share NetBox without fighting over it. - Ansible deploy role (
ansible/roles/argus_deploy/): installs the self-contained stack fromdeploy/on a Docker host. Repo checkout,.envrendering (secrets generated once and reused, unmanaged keys carried over),docker compose up.
Contributing
This is a personal project run with the discipline of a shared one: changes land via signed-commit pull requests with a CHANGELOG entry, decisions are captured as ADRs, and work is tracked in issues. See CONTRIBUTING.md.
License
Argus MCP questions
What does Argus do with NetBox?
Argus treats NetBox as the single source of truth and works to keep it continuously reflecting reality by discovering the live network and reconciling differences.
Can I use Argus with Claude Code or other AI agents?
Yes, Argus exposes its capabilities to MCP-compliant coding agents like Claude Code, Codex, and Kimi as a set of tools.
How can I add support for new network hardware?
You can add support by creating a self-contained VendorPack using the provided template.