MCP-Telecom

Let AI agents talk to your network equipment.

The first MCP server for Nokia SR OS, Cisco IOS-XR, Juniper Junos, Arista EOS, and Cisco NX-OS routers.

"Hey Claude, show me the BGP summary on nokia-pe1 and check if any peers are down."

MCP-Telecom in action — asking Claude about network devices, tools, vendors, and telemetry paths

MCP-Telecom bridges the gap between AI assistants and network infrastructure. It implements the Model Context Protocol (MCP) to give AI agents like Claude and GPT secure, read-only access to your network devices via SSH — no custom scripts, no fragile automation, just natural language.

Why MCP-Telecom?

Features

• Multi-Vendor Support — Nokia SR OS, Cisco IOS / IOS-XR / NX-OS, Juniper Junos, Arista EOS
• 60+ Network Tools — BGP, OSPF, MPLS, interfaces, alarms, NTP, ARP, MAC tables, and more
• Vendor Abstraction — Say bgp_summary and get the right command for any vendor
• NETCONF/YANG — Structured data retrieval via NETCONF alongside traditional SSH CLI
• Streaming Telemetry — gNMI-based telemetry subscriptions with in-memory cache
• SNMP MIB Polling — Query SNMP OIDs, walk MIB subtrees, device overviews via SNMPv2c/v3
• Topology Discovery — Auto-build network maps from LLDP/CDP data with path finding
• Multi-Device Parallel Queries — Run commands across all devices simultaneously via thread pool
• Config Compliance — Check configs against 20+ security best-practice rules with scoring
• Connection Pooling — Persistent SSH sessions with idle timeout and automatic cleanup
• Web Dashboard — Real-time device status dashboard with auto-refresh (FastAPI)
• Prometheus Metrics — Export device health and command metrics for Grafana dashboards
• Containerlab Integration — Generate lab topologies for testing without production access
• Safety First — Only read-only commands allowed; destructive commands are blocked
• Audit Logging — Every command execution recorded in structured JSONL format
• Config Backup & Diff — Backup running configs and compare against previous versions
• Health Checks — Test device reachability with response time measurement
• MCP Resources — Device inventory, topology, telemetry, and compliance as browseable resources
• Troubleshooting Prompts — Built-in BGP, interface, and health audit workflows
• Nokia Service Tools — VPRN, VPLS, and SAP inspection for Nokia SR OS
• PyPI Ready — pip install mcp-telecom with optional extras
• Docker Support — Run containerized with docker-compose
• CI/CD — GitHub Actions with multi-Python-version testing and PyPI publishing

Architecture

┌──────────────────────────────────────────────────────────────┐
│                     AI Agent (Claude/GPT)                    │
│                                                              │
│  "Check compliance on all routers"                           │
│  "Run BGP summary across all devices in parallel"            │
│  "Generate a containerlab topology for testing"              │
└──────────────────────┬───────────────────────────────────────┘
                       │  MCP Protocol (stdio)
                       ▼
┌──────────────────────────────────────────────────────────────┐
│                  MCP-Telecom Server v0.2.0                   │
│                                                              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────────┐  │
│  │ 60+ Tools│ │Resources │ │ Prompts  │ │ Safety/Audit   │  │
│  └────┬─────┘ └──────────┘ └──────────┘ └────────────────┘  │
│       │                                                      │
│  ┌────▼──────────────────────────────────────────────────┐   │
│  │            Vendor Command Mappings (35+ ops)          │   │
│  │   Nokia ── Cisco ── Juniper ── Arista ── NX-OS        │   │
│  └────┬──────────┬──────────┬──────────┬─────────────────┘   │
│       │          │          │          │                      │
│  ┌────▼────┐ ┌───▼────┐ ┌──▼──────┐ ┌─▼───────┐             │
│  │  SSH    │ │NETCONF │ │Telemetry│ │  SNMP   │             │
│  │(Netmiko)│ │(YANG)  │ │ (gNMI)  │ │(pysnmp) │             │
│  └────┬────┘ └───┬────┘ └──┬──────┘ └─┬───────┘             │
│       │          │         │          │                      │
│  ┌────▼──────────▼─────────▼──────────▼───────────────────┐  │
│  │  Connection Pool │ Parallel Executor │ Compliance      │  │
│  │  Topology │ Dashboard │ Prometheus │ Containerlab      │  │
│  └────────────────────────────────────────────────────────┘  │
└──────────────┬──────────────┬──────────────┬─────────────────┘
               │              │              │
               ▼              ▼              ▼
     ┌──────────────┐ ┌──────────┐ ┌──────────────┐
     │ Nokia SR OS  │ │ Cisco XR │ │ Juniper/EOS  │
     └──────────────┘ └──────────┘ └──────────────┘

Quick Start

Prerequisites

• Python 3.10+
• uv package manager
• SSH access to your network devices

Installation

# Install from PyPI
pip install mcp-telecom

# With optional extras
pip install mcp-telecom[netconf]     # NETCONF/YANG support
pip install mcp-telecom[telemetry]   # gNMI streaming telemetry
pip install mcp-telecom[snmp]        # SNMP MIB polling
pip install mcp-telecom[dashboard]   # Web dashboard (FastAPI)
pip install mcp-telecom[metrics]     # Prometheus metrics exporter
pip install mcp-telecom[all]         # Everything

# Or from source
git clone https://github.com/Avinash-Amudala/MCP-Telecom.git
cd MCP-Telecom
uv sync       # or: pip install -e .

Configure Your Devices

# Copy the example config and edit with your device details
cp devices.yaml.example devices.yaml

Edit devices.yaml with your actual device credentials:

nokia-pe1:
  device_type: nokia_sros
  host: 192.168.1.1
  username: your_username
  password: "${NOKIA_PASSWORD}"   # replace with real creds
  port: 22

cisco-xr1:
  device_type: cisco_xr
  host: 192.168.2.1
  username: your_username
  password: "${CISCO_PASSWORD}"

juniper-mx1:
  device_type: juniper_junos
  host: 192.168.3.1
  username: your_username
  password: "${JUNIPER_PASSWORD}"

Test with MCP Inspector

npx @modelcontextprotocol/inspector uv run mcp-telecom

Use with Claude Desktop

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "mcp-telecom": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/MCP-Telecom",
        "mcp-telecom"
      ],
      "env": {
        "MCP_TELECOM_DEVICES_FILE": "/path/to/MCP-Telecom/devices.yaml"
      }
    }
  }
}

Once configured, the server appears in Claude Desktop under Settings → Developer:

MCP-Telecom registered and running in Claude Desktop's Developer settings

Available Tools

Routing & Protocols

Interfaces & Layer 2

System Monitoring

Configuration & Operations

NETCONF / YANG

Streaming Telemetry (gNMI)

Topology Discovery

SNMP MIB Polling

Multi-Device Parallel Queries

Config Compliance

Containerlab Integration

Dashboard & Metrics

How Companies Use MCP-Telecom

MCP-Telecom is designed for zero-friction deployment inside enterprise networks:

Setup for Teams (5 minutes)

1. Install: pip install mcp-telecom on any machine with SSH access to network devices
2. Configure: Copy devices.yaml.example → devices.yaml and fill in device IPs + credentials
3. Run: Add the MCP server to Claude Desktop config (one JSON block)
4. Done: Engineers can now query any device through natural language

Security Model

• Credentials stay local — devices.yaml lives on the engineer's machine, never leaves the network
• Read-only by default — Only show/display commands allowed; configure/delete/shutdown blocked
• Full audit trail — Every command logged with timestamp, device, user, success/failure
• No cloud dependency — MCP runs over local stdio; no data leaves your infrastructure
• Compliance built-in — Run compliance_check to validate configs against security baselines

Enterprise Deployment Options

Is It Hard to Set Up?

No. The entire setup is: install the package, edit one YAML file with your device IPs and credentials, and add one config block to Claude Desktop. There is no cloud account, no API key from us, no SaaS subscription. Everything runs locally inside your network perimeter.

For teams, a network admin creates one devices.yaml and shares it internally. Each engineer points their Claude Desktop config to the shared MCP server or runs their own local instance.

Supported Platforms

Safety & Security

MCP-Telecom enforces strict read-only access:

• Allowed: show, display, ping, traceroute commands
• Blocked: configure, set, delete, commit, reload, shutdown, write, clear, reset, debug, and 20+ other dangerous patterns
• Audit Trail: Every command execution is logged with timestamp, device, success/failure, and output length

[2026-04-06T12:00:00Z] OK   nokia-pe1       show router bgp summary
[2026-04-06T12:00:05Z] OK   cisco-xr1       show ip interface brief
[2026-04-06T12:00:10Z] FAIL cisco-xr1       configure terminal  ← BLOCKED

Docker

# Build and run
docker-compose up -d

# Or build manually
docker build -t mcp-telecom .
docker run -v ./devices.yaml:/app/devices.yaml:ro mcp-telecom

Development

# Install dev dependencies
uv sync --all-extras

# Run tests
uv run pytest tests/ -v

# Lint
uv run ruff check src/ tests/

# Test with MCP Inspector
npx @modelcontextprotocol/inspector uv run mcp-telecom

Project Structure

MCP-Telecom/
├── src/mcp_telecom/
│   ├── __init__.py          # Package init
│   ├── server.py            # MCP server (60+ tools, resources, prompts)
│   ├── connection.py        # SSH connection manager (Netmiko)
│   ├── models.py            # Pydantic data models
│   ├── safety.py            # Command safety validation
│   ├── audit.py             # Structured JSONL audit logging
│   ├── topology.py          # LLDP/CDP topology discovery & path finding
│   ├── pool.py              # Connection pooling (persistent SSH sessions)
│   ├── parallel.py          # Multi-device parallel query executor
│   ├── compliance.py        # Config compliance checker (20+ rules)
│   ├── dashboard.py         # Real-time web dashboard (FastAPI)
│   ├── metrics.py           # Prometheus metrics exporter
│   ├── containerlab.py      # Containerlab topology generator
│   ├── vendors/
│   │   ├── __init__.py
│   │   └── mappings.py      # Vendor-specific command mappings (6 vendors)
│   ├── transports/
│   │   ├── __init__.py
│   │   ├── netconf.py       # NETCONF/YANG transport (ncclient)
│   │   ├── telemetry.py     # gNMI streaming telemetry collector
│   │   └── snmp.py          # SNMP MIB polling (pysnmp)
│   └── tools/
│       ├── __init__.py
│       ├── routing.py       # Routing protocol tools
│       ├── interfaces.py    # Interface monitoring tools
│       └── system.py        # System monitoring tools
├── tests/                   # 157 tests
├── assets/                  # Demo GIF, screenshots
├── .github/workflows/
│   ├── ci.yml               # CI pipeline (Python 3.10-3.12 + Docker)
│   └── publish.yml          # PyPI publish on GitHub release
├── pyproject.toml           # Project config with optional extras
├── Dockerfile               # Container support
├── docker-compose.yml       # Docker Compose config
├── devices.yaml.example     # Example device config
└── README.md                # This file

Roadmap

• NETCONF/YANG — Structured data retrieval via NETCONF
• Streaming telemetry — gNMI-based real-time telemetry collection
• Topology discovery — Auto-build network maps from LLDP/CDP
• PyPI publishing — pip install mcp-telecom
• SNMP MIB polling — SNMPv2c/v3 OID queries and MIB walks
• Connection pooling — Persistent SSH sessions with idle timeout
• Config compliance — 20+ rules, scoring, remediation advice
• Multi-device parallel queries — Thread pool across all devices
• Web dashboard — FastAPI real-time device status dashboard
• Prometheus metrics — Export to Grafana with 8 metric types
• Containerlab integration — Generate lab topologies for testing
• MCP Registry listing — Publish to the official MCP Registry
• Remote MCP server — HTTP/SSE transport for Claude's MCP Directory

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

MIT — Avinash Amudala

Built with MCP + Netmiko + FastMCP