TO
AI & ML

Topolograph MCP Server: LLM-Enabled OSPF/IS-IS Analysis

Analyze OSPF and IS-IS networks with an MCP server that enables LLMs to query events, map topologies, and calculate paths.

View on GitHub
Quick Install
npx -y @Vadims06/topolograph-mcp-server

Overview

Topolograph MCP Server is a Model Context Protocol (MCP) adapter that exposes OSPF and IS-IS network state as queryable tools for large language models (LLMs) and external automation. It ingests routing protocol events, adjacency information, and link-state databases, and translates that data into structured resources an LLM can call to answer questions, map topologies, and compute forwarding paths.

The server is useful for network engineers and AI/ML developers who want to integrate real network telemetry and routing logic into conversational assistants, automated runbooks, or analysis pipelines. Instead of giving an LLM raw logs or opaque dumps, the MCP server provides well-defined operations (tools) that return concise topology, event, and path information, reducing hallucinations and enabling actionable outputs.

Features

  • Exposes OSPF and IS-IS topology and event data through an MCP-compatible API
  • Provides topology mapping (nodes, links, adjacency state)
  • Computes paths and next-hops based on current LSDB/fib state
  • Event querying: filters protocol events (flaps, LSP/MSA, SPF triggers)
  • LLM-friendly tool semantics: small, deterministic JSON responses
  • Runs as a standalone service (Docker-friendly) and can be integrated into LLM agent flows
  • Open source — repository and examples on GitHub

Installation / Configuration

Clone the repository and run locally or in Docker. The examples below assume a UNIX-like environment.

Clone repository:

git clone https://github.com/Vadims06/topolograph-mcp-server.git
cd topolograph-mcp-server

Run with Docker (recommended for isolation):

# build image
docker build -t topolograph-mcp-server .

# run container, expose port 8080
docker run -d --name topo-mcp -p 8080:8080 \
  -e MCP_BIND_ADDR=0.0.0.0 -e MCP_PORT=8080 \
  topolograph-mcp-server

Run directly with Python (if a Python runtime is provided by the repo):

# create venv and install deps (example)
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# start server
python -m topolograph_mcp_server --host 0.0.0.0 --port 8080

Configuration options (typical environment variables or CLI flags):

  • MCP_BIND_ADDR / –host — bind address
  • MCP_PORT / –port — listening port
  • LOG_LEVEL — logging verbosity
  • DATA_SOURCES — path(s) to LSDB/routing dumps or sockets for live updates

Refer to the repository README for full config options and platform-specific instructions.

Available Tools

The MCP server exposes a small set of discrete tools for LLMs to call. Typical tool names and payloads:

  • topology.get_nodes

    • Description: Returns node list and attributes (router id, area, system name)
    • Response: JSON array of node objects

  • topology.get_links

    • Description: Returns link list with endpoints, cost, and state
    • Response: JSON array of link objects

  • events.query

    • Description: Filter protocol events (time range, type, node)
    • Request example:
      {"type":"ospf","event":"adjacency_down","since":"2026-04-01T00:00:00Z"}

  • path.calculate

    • Description: Compute best path between two prefixes or nodes using current LSDB/FIB
    • Request example:
      {"src":"10.0.0.1","dst":"10.0.2.0/24","protocol":"ospf"}
    • Response example:
      {"hops":["R1","R3","R5"],"next_hop":"10.0.3.2","total_cost":20}

These tools are intentionally narrow and deterministic to keep LLM outputs grounded.

Use Cases

  • Root-cause analysis with an LLM assistant

    • Example: “Which IS-IS adjacencies flapped in area 49.0001 over the last 24 hours?” — The agent calls events.query to return filtered adjacency events, then summarizes the likely causes.

  • On-demand topology visualization

    • Example: “Show the topology around router R5 and list its neighbors.” — The agent calls topology.get_nodes and topology.get_links, builds a local graph, and renders a concise neighbor list or DOT graph.

  • Path validation for change windows

    • Example: “If I change link L1 cost from 10 to 50, what will be the new path from prefix A to B?” — The agent can request path.calculate with modified-cost parameters (or simulate changes server-side) to show alternative next-hops and cost deltas.

  • Automated incident reports

    • Example: Generate a human-readable timeline of SPF runs and network events tied to a service degradation window using events.query and path.calculate to correlate outages to topology changes.

Example API Call (curl)

Request topology nodes:

curl -s http://localhost:8080/mcp/tool/topology.get_nodes | jq

Calculate a path:

curl -X POST http://localhost:8080/mcp/tool/path.calculate \
  -H "Content-Type: application/json" \
  -d '{"src":"R1","dst":"10.0.2.0/24","protocol":"ospf"}' | jq

Resources

  • GitHub repository: https://github.com/Vadims06/topolograph-mcp-server
  • Use the repo issues and examples for sample data ingestion and agent integrations

Notes

  • The MCP server is designed to reduce the cognitive load on LLMs by providing precise, machine-readable tools. Ensure your LLM agent only calls the tools needed for a task and validates responses before performing network changes.
  • For production use, integrate secure access control, TLS, and authentication between your LLM agent and the MCP server.
Tags:ai-ml