nautobot-mcp

A read-only, production-shaped Model Context Protocol server for Nautobot — the network source of truth (DCIM + IPAM). Same architecture as the sibling meraki-mcp: one response contract, one lifecycle owner, one API seam, resolution baked in, response-size budget, read-only by default.

Built on the MCP Python SDK (FastMCP) over Nautobot's REST API via httpx.

Coverage strategy (grounded in the API)

Nautobot's OpenAPI schema (v3.1) has 678 GET operations across ~100 object types. Wrapping each as a tool would wreck LLM selection, so coverage is layered:

• Power tools (the breadth): nautobot_graphql (run a read-only GraphQL query — the ideal way to traverse the source of truth in one call), nautobot_graphql_schema (introspect root query fields / a type's fields so the model writes a correct query first), nautobot_saved_query (run a stored GraphQL query by name), and nautobot_query (generic reader over 75 curated object types via the uniform REST interface — including plugin apps: golden-config compliance, Device Lifecycle CVE/hardware/software, VPN, load-balancers — with q search + filter passthrough).
• Workflow tools (job-driven, multi-endpoint — the real value): nautobot_data_quality_audit (SoT hygiene: what's undocumented — missing primary IPs/racks/platforms/software, unassigned IPs), nautobot_site_report (one-call site picture: devices by role/status + IPAM + racks + gaps), nautobot_device_readiness (deployment/documentation checklist, GO/NO-GO), nautobot_rack (elevation + free U), nautobot_ip_allocate (next free IP/subnet suggestion).
• Sharp purpose tools (the common intents): nautobot_find, nautobot_device, nautobot_device_interfaces, nautobot_interface (single-interface detail), nautobot_device_config_context, nautobot_cabling, nautobot_list_devices (filter by location/role/status/manufacturer/model/platform/software_version — "which devices run 17.12.3?"), nautobot_location, nautobot_ip_lookup, nautobot_prefix (+ available IPs/prefixes), nautobot_list_prefixes, nautobot_list_vlans, nautobot_vlan (single-VLAN detail + mapped prefixes), nautobot_vlan_allocate (next free VID), nautobot_status_overview, nautobot_object_changes (SoT audit log).
• Optional (flagged, network-automation apps): nautobot_jobs, nautobot_circuits, nautobot_lifecycle_report (EoX/end-of-support, Device Lifecycle app), and the Golden Config layer — nautobot_config_compliance (per-device or per-site compliance), nautobot_device_config (stored backup/intended/compliance text), and nautobot_config_search (grep config text across the fleet — "who still runs telnet?"). Enable with NAUTOBOT_MCP_ENABLE_OPTIONAL_TOOLS=true.

Tool-structure ergonomics (for the LLM): every list tool returns a uniform envelope ({kind, count, items}) with cursor pagination (next_offset → pass back as offset); an unknown filter is a self-correcting error that returns the valid filter names for that type (not a hard failure); nautobot_query defers to the sharp tools when one exists.

Resources: nautobot://locations, nautobot://device-roles, nautobot://statuses, nautobot://manufacturers (titled). Prompts (12 playbooks): /find, /device_report, /ip_lookup, /site_inventory, /data_quality, /device_readiness, /prefix_report, /vlan_report, /connectivity, /capacity, /change_history, /compliance_check — with argument completion (location/device autocomplete from live Nautobot data). Every tool + power endpoint was validated live against demo.nautobot.com.

LLM-facing conformance (MCP SDK): every tool parameter carries a Field(description=…) and closed sets are Literal enums, so the generated inputSchema guides the model on every argument; tools return a Pydantic ToolResult, so each also advertises an outputSchema + structuredContent; read-only tools are annotated readOnlyHint/idempotentHint/openWorldHint; genuine failures set the protocol isError (self-correcting ambiguity/not-found do not); fan-out tools report progress. Covered by in-memory client-session tests (tests/test_server_session.py). Scored ≈94/100 against MCP_ENGINEERING_STANDARD.md.

Shape (mirrors meraki-mcp)

• One contract — every tool returns ToolResult{summary, data, meta, error}; payloads projected to declared fields (nested objects compacted via ref), arrays capped.
• Response-size budget — the registrar runs enforce_budget so no result overflows the agent context (flagged in meta.truncated/meta.note).
• One seam — all REST calls go through NautobotGateway (httpx + concurrency limit + timeout + bounded retry on transient timeout/502-504 + error normalization + logging); one _send owns the HTTP call site.
• One catalog — core/catalog.py is the single registry of object-type→REST-path knowledge; the generic query tool, the resolver, and the change-audit aliases all derive from it, so adding an object type or plugin app is a one-file edit.
• Names in, IDs never invented — the Resolver turns "ams01"/"AMS"/"10.0.0.0/24" into objects; ambiguity returns the candidate list.
• Read-only — no write tools.

Run

uv sync                       # or: pip install -e ".[dev]"
cp .env.example .env          # NAUTOBOT_URL + NAUTOBOT_TOKEN (read-only)
uv run python -m nautobot_mcp # stdio (waits for an MCP client — normal)
# HTTP:  $env:NAUTOBOT_MCP_TRANSPORT="streamable-http"; uv run python -m nautobot_mcp
# Inspector:  uv run mcp dev src/nautobot_mcp/server.py:build_server

Prefer python -m nautobot_mcp over the nautobot-mcp console script: on locked-down Windows, Application Control (Smart App Control / WDAC) can block the generated nautobot-mcp.exe shim (OS error 4551). python -m runs the trusted interpreter directly.

Test it

1. Offline gates: pytest -q · lint ruff check src tests scripts · types mypy (strict-ish: check_untyped_defs, clean across all modules).
2. Live smoke (public demo): with NAUTOBOT_URL=https://demo.nautobot.com and the demo token in .env: python scripts/smoke_test.py (add a device name, e.g. python scripts/smoke_test.py ams01-edge-01).
3. HTTP / Copilot Studio: NAUTOBOT_MCP_TRANSPORT=streamable-http nautobot-mcp → http://127.0.0.1:8000/mcp (or docker build -t nautobot-mcp . && docker run -p 8000:8000 -e NAUTOBOT_URL=... -e NAUTOBOT_TOKEN=... nautobot-mcp). No auth yet (OAuth planned) — keep behind a tunnel/gateway.

Never commit a real token. .env is git-ignored; .env.example holds a placeholder.