To build an MCP server to manage Cisco devices, wrap a network library such as Netmiko in a few typed Python functions, register them as tools with the official MCP Python SDK, and let your AI client call those tools over stdio. Start with read only tools (list devices, run an allowed show command, back up the running config), keep credentials in environment variables, and add one narrow change tool that plans by default and only applies when a flag is set. If you use Meraki, Catalyst Center or Cisco Modeling Labs, Cisco already ships MCP servers you can run instead.

This guide walks through a server we built and ran on November 13, 2026, then compares it with the Cisco servers that exist today. If MCP is new to you, start with what is MCP; for the general pattern of writing a server, our MCP server in Python tutorial covers the SDK basics this guide builds on.

Should you build your own Cisco MCP server?

Check what already exists before you write code. Cisco and its engineers have published several servers, and each one fits a different part of a network.

Your gearReady made optionWhat it can do
MerakiCisco hosted Meraki MCP at mcp.meraki.com/mcp, or the open source buildRead only Dashboard API queries
Catalyst CenterOpen source Catalyst Center MCP server (beta)Talks to Catalyst Center, not to each switch
Lab devices in CMLcml-mcp from PyPIBuilds labs, starts nodes, runs CLI commands through pyATS
IOS and IOS XE over SSHCiscoDevNet pyATS MCP sample (1.0.0 beta)Five tools: list, show, health check, backup, guarded config
Any SSH device with pyATSCommunity pyATS_MCP34 tools, Streamable HTTP only

The Meraki MCP docs describe two tools, semantic_search and execute_api, and say the server supports read operations only. They also warn that an agent holding a read and write API key may call the Dashboard API directly, so give it a key tied to read only access. Cisco announced the Meraki hosted server and the Meraki and Catalyst Center open source servers as beta in an August 2026 community post.

For devices you reach over SSH, the CiscoDevNet pyATS MCP server is the closest official reference. Its README marks it 1.0.0 beta, "intended for lab environments, not production networks", tested on IOSv and IOS XE nodes in Cisco Modeling Labs, and its apply_config tool refuses to run unless PYATS_MCP_ALLOW_CONFIG=true. The community pyATS_MCP project goes much wider, with 34 tools and Genie learn and diff, but it dropped stdio and serves Streamable HTTP only.

Build your own when your devices are reached over SSH, your team already uses Netmiko, and you want a small tool list that matches your runbook exactly. A server with four tools you understand is easier to review than one with 34.

What you need

  • Python 3.11 or newer. Netmiko 4.8.0, released September 21, 2026, declares Python 3.11 and up in its project file.
  • The MCP Python SDK 2.x. In v2 the server class is MCPServer; old posts that import FastMCP from mcp.server.fastmcp fail on a fresh install.
  • An SSH reachable lab device. Use a Cisco Modeling Labs node or a DevNet Sandbox before you ever point this at production.
  • An MCP client such as Claude Code, Cursor or GitHub Copilot in VS Code.

Install both libraries into a virtual environment with pip install mcp netmiko. Netmiko pulls in TextFSM and the ntc-templates collection, which is what turns raw show output into rows the model can read.

Step 1: Describe your devices

Keep the inventory in a JSON file and the credentials in the environment, so neither appears in a prompt or in your repository:

{"r1": {"host": "192.0.2.11", "device_type": "cisco_ios"},
 "sw1": {"host": "192.0.2.21", "device_type": "cisco_xe"}}

The model only ever sees the names r1 and sw1. It can't invent a new IP address and reach it, because the server refuses any name that isn't in the file.

Step 2: Write the server

Save this as cisco_mcp.py:

import json, logging, os, re
from pathlib import Path
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError
from mcp.types import ToolAnnotations
from netmiko import ConnectHandler

log = logging.getLogger("cisco_mcp")  # logs go to stderr, never stdout
INVENTORY = json.loads(Path(os.environ["CISCO_INVENTORY"]).read_text())
ALLOW_CHANGES = os.environ.get("CISCO_ALLOW_CHANGES") == "true"
SHOW_PREFIXES = ("show version", "show ip interface brief", "show interfaces",
                 "show ip route", "show vlan", "show cdp neighbors", "show logging")
BAD = re.compile(r"[\r\n;]")
PIPE_OK = re.compile(r"^[^|]+(\| (include|exclude|section|begin) [\w ./:-]+)?$")
IFACE = re.compile(r"^(GigabitEthernet|TenGigabitEthernet|FastEthernet|Loopback|Vlan)\d+(/\d+){0,2}$")

mcp = MCPServer("cisco")

def connect(device: str):
    if device not in INVENTORY:
        raise ToolError(f"unknown device {device!r}; call list_devices")
    d = INVENTORY[device]
    return ConnectHandler(device_type=d["device_type"], host=d["host"], port=d.get("port", 22),
                          username=os.environ["CISCO_USER"], password=os.environ["CISCO_PASS"])

@mcp.tool(annotations=ToolAnnotations(read_only_hint=True))
def list_devices() -> list[str]:
    """List the device names this server is allowed to reach."""
    return sorted(INVENTORY)

@mcp.tool(annotations=ToolAnnotations(read_only_hint=True))
def show(device: str, command: str) -> str | list[dict]:
    """Run one allowed show command. Returns parsed rows when a template exists."""
    cmd = command.strip()
    if BAD.search(cmd) or not PIPE_OK.match(cmd) or not cmd.startswith(SHOW_PREFIXES):
        raise ToolError(f"command not allowed: {cmd!r}")
    with connect(device) as conn:
        return conn.send_command(cmd, use_textfsm=True)

@mcp.tool(annotations=ToolAnnotations(read_only_hint=True))
def backup_config(device: str) -> str:
    """Return the running configuration of a device."""
    with connect(device) as conn:
        return conn.send_command("show running-config", read_timeout=120)

@mcp.tool(annotations=ToolAnnotations(destructive_hint=True, idempotent_hint=True))
def set_interface_description(device: str, interface: str, description: str,
                              apply: bool = False) -> dict:
    """Set an interface description. With apply=false it only returns the planned lines."""
    if not IFACE.match(interface):
        raise ToolError(f"bad interface name: {interface!r}")
    if not re.fullmatch(r"[\w .:/-]{1,60}", description):
        raise ToolError("description: letters, digits, spaces and . : / - only, max 60")
    lines = [f"interface {interface}", f"description {description}"]
    if not apply:
        return {"applied": False, "planned": lines}
    if not ALLOW_CHANGES:
        raise ToolError("changes are disabled; set CISCO_ALLOW_CHANGES=true")
    log.warning("CHANGE %s: %s", device, lines)
    with connect(device) as conn:
        out = conn.send_config_set(lines)
        conn.save_config()
    return {"applied": True, "planned": lines, "output": out}

if __name__ == "__main__":
    mcp.run()

Why the tools look like this

An allowlist, not a blocklist. The show tool accepts only commands that start with a known prefix, rejects newlines and semicolons, and allows one pipe filter. A blocklist of scary words always misses something. When we sent reload, and then show version followed by a newline and reload, both were refused before any SSH session opened.

Use ToolError for messages the model should read. In SDK 2.3.0, a plain ValueError reached our client as a bare "Error executing tool show" with no reason attached. Raising ToolError passed the reason through ("command not allowed", "unknown device", "call list_devices"), which lets the model correct itself instead of guessing.

Parsed output. With use_textfsm=True, Netmiko ran show ip interface brief through the ntc-templates parser and returned a list of rows with interface, address, status and protocol. Structured rows are shorter than raw CLI text and much harder for the model to misread. If no template matches a command, you get the plain text back.

One narrow change tool. We didn't write a generic send_config tool. set_interface_description can only touch one line under one interface, validates both inputs with a strict pattern, returns the planned lines unless apply is true, and still refuses unless the operator set CISCO_ALLOW_CHANGES=true when starting the server. Add more change tools the same way: one tool per runbook task, each with its own validation.

Annotations are labels, not locks. read_only_hint and destructive_hint help a client decide when to ask you before a call. The MCP tools specification says clients must treat annotations as untrusted unless they come from trusted servers. The real guard is the code inside the tool.

Step 3: Test it without a model

The SDK's Client can open the server object in memory, so you can check every refusal without a chat window. Set CISCO_INVENTORY, CISCO_USER and CISCO_PASS, then call list_devices, a good show, a bad show and the change tool with and without apply. Most of what can go wrong here is input validation, and that is cheap to test.

On our run, the planned change came back as two lines, the apply call failed with the "changes are disabled" message, and after we flipped the flag the new description showed up in backup_config.

Step 4: Connect it to your client

For Claude Code, register the launch command and pass the environment:

claude mcp add cisco \
  -e CISCO_INVENTORY=/abs/path/inventory.json -e CISCO_USER=netops -e CISCO_PASS="$CISCO_PASS" \
  -- /abs/path/venv/bin/python /abs/path/cisco_mcp.py

Cursor and VS Code take the same command and environment in their mcp.json files; our MCP server in GitHub Copilot guide shows where each editor reads them. Use absolute paths, because clients start servers from their own working directory, and see run an MCP server locally if the server doesn't appear.

Leave CISCO_ALLOW_CHANGES out of the everyday config. Start a second, separately named server entry with the flag only for a change window, and remove it afterwards.

Safety rules for network MCP servers

  • Lab first. Cisco's own sample says lab only. Prove your tools against CML or a sandbox before any production device.
  • A dedicated account. Give the server its own AAA user with a privilege level or command authorization that matches the tools. If the device itself denies configure terminal to that user, a bug in your validation can't change anything.
  • Treat device output as untrusted. Interface descriptions, banners and log lines are text an attacker may control. The CiscoDevNet README calls this out: an interface description could contain text that looks like an instruction to the model.
  • Never print to stdout. On stdio, stdout carries protocol messages. Netmiko and Paramiko log through Python logging, which goes to stderr by default; keep it that way.
  • Keep a log of every change. The log.warning line records device and lines before the change runs. Ship stderr to your logging system.

If you would rather go through an API than CLI, the same design works with RESTCONF or a controller. Our MCP server vs API guide explains where an MCP layer adds value over calling an API directly.

FAQ

Is there an official Cisco MCP server?

Yes, for some products. Meraki has a Cisco hosted, read only server plus an open source build, Catalyst Center has an open source server in beta, and CiscoDevNet publishes a pyATS based sample for IOS and IOS XE devices marked for lab use. Cisco Modeling Labs has cml-mcp, version 0.40.0 on PyPI as of November 13, 2026.

Netmiko or pyATS for a Cisco MCP server?

Netmiko is lighter: one SSH library with TextFSM parsing, and the code in this guide is about 70 lines. pyATS with Genie brings deeper parsers, device state snapshots and before and after diffs, which is why both Cisco's sample and the community server use it. Pick Netmiko for a small runbook server and pyATS if you already keep testbed files.

Can an MCP server push configuration to Cisco devices safely?

It can, if every write goes through a narrow tool with strict input checks, a plan step, an operator controlled flag and a device account limited by AAA. Avoid a generic tool that accepts any configuration lines; Cisco's sample keeps its apply_config tool off by default for the same reason.

Does this work with NX-OS or IOS XR?

Netmiko supports cisco_nxos and cisco_xr device types, so the same server shape applies. Command prefixes, interface names and parsing templates differ by platform, so extend the allowlist and test on each one. We only tested against a simulated IOS device.

Should the server run over stdio or HTTP?

Use stdio while one engineer runs it on a laptop or jump host. Move to Streamable HTTP when a team shares one server, and put authentication in front of it first, as the Python MCP server guide describes.