네트워크 MCP 서버

AI 에이전트가 SSH를 통해 Cisco IOS-XE 네트워크 장치와 상호 작용할 수 있게 해주는 모델 컨텍스트 프로토콜(MCP) 서버입니다. FastMCP와 Netmiko를 사용하여 Python으로 구축되었습니다.

이 서버는 7개의 도구(읽기 5개 + 쓰기 2개)를 제공하며, 각 도구는 엄격한 입력 유효성 검사와 명확한 설명을 포함하고 있어 LLM 에이전트가 이를 자율적으로 발견하고 사용할 수 있습니다.

과정: 에이전트 AI 및 자동화 — 셰리던 칼리지 작성자: Ahmed 강사: Sebastian

실습 환경

이 프로젝트는 Cisco의 Always-On IOS-XE DevNet Sandbox를 대상으로 합니다. 무료이며 공개적으로 접근 가능하고, 예약이 필요 없으며 항상 가동 중입니다.

설정	값
호스트	`sandbox-iosxe-latest-1.cisco.com`
포트	`22` (SSH)
사용자 이름	`admin`
비밀번호	`C1sco12345`
장치 유형	Cisco IOS-XE (Catalyst 8000v)

참조: Cisco DevNet — Always-On Sandboxes.

내 컴퓨터에서 빠른 연결 확인:

ssh admin@sandbox-iosxe-latest-1.cisco.com
# password: C1sco12345

Router#(또는 유사한) 프롬프트가 나타나야 합니다. 이 작업이 성공하면 MCP 서버도 작동합니다.

샌드박스는 공유 환경입니다. 변경 사항을 작게 유지하고 방해가 되지 않도록 하십시오(예: 인터페이스 설명만 수정하고, 인터페이스를 끄거나 IP를 변경하지 마십시오).

설치

**Python 3.10+**가 필요합니다.

# 1. Clone / copy the project
cd network-mcp-server

# 2. Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate    # on Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

종속성:

mcp[cli] — MCP Python SDK (FastMCP 제공)
netmiko — 다중 공급업체 SSH/CLI 라이브러리
python-dotenv — 로컬 개발을 위해 .env 로드

서버 실행

옵션 A — 독립형 (로컬 테스트용)

cp .env.example .env
# edit .env if your lab uses different credentials

python server.py

서버는 stdio를 통해 실행되므로 MCP JSON-RPC 메시지를 위해 stdin을 기다립니다. 실제로는 수동으로 호출하지 않고 Claude Desktop(아래 참조)이나 mcp 개발 CLI를 연결하게 됩니다.

옵션 B — 대화형 개발 검사기

mcp dev server.py

브라우저에서 MCP 검사기를 열어 도구 목록을 확인하고 수동으로 호출할 수 있습니다.

도구

읽기 도구

도구	설명
`get_device_info`	호스트 이름, 모델, 소프트웨어 버전, 가동 시간, 일련번호. `show version`을 파싱합니다.
`get_interfaces`	상태, IP, 설명이 포함된 모든 인터페이스. `show ip interface brief` + `show interfaces description`을 파싱합니다.
`get_routes`	IPv4 라우팅 테이블. `show ip route`를 구조화된 항목으로 파싱합니다.
`get_arp_table`	IP-MAC 매핑. `show ip arp`를 파싱합니다.
`get_running_config`	전체 실행 구성 또는 단일 섹션(예: `interface GigabitEthernet1`). 선택적 `section` 인수를 사용합니다.

쓰기 도구

도구	설명
`configure_interface_description`	인터페이스에 설명을 설정하고 다시 읽어 변경 사항이 적용되었는지 확인합니다. 인수: `interface`, `description`.
`save_config`	`copy running-config startup-config`를 실행하여 재부팅 후에도 변경 사항을 유지합니다.

모든 도구 출력은 LLM이 구조화된 데이터를 추론할 수 있도록 JSON 문자열로 제공됩니다. Netmiko의 TextFSM 파서가 출력을 처리할 수 없는 경우, 서버는 {"raw": "..."} 래퍼 내의 원시 CLI 텍스트로 대체합니다.

Claude Desktop에 연결

Claude Desktop의 구성 파일 위치:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
아래 블록을 파일에 병합합니다(server.py에 대한 전체 절대 경로를 사용하십시오):

{
  "mcpServers": {
    "network-mcp-server": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/network-mcp-server/server.py"],
      "env": {
        "DEVICE_HOST": "sandbox-iosxe-latest-1.cisco.com",
        "DEVICE_PORT": "22",
        "DEVICE_USERNAME": "admin",
        "DEVICE_PASSWORD": "C1sco12345",
        "DEVICE_TYPE": "cisco_xe"
      }
    }
  }
}

복사 가능한 버전은 claude_desktop_config.example.json에 있습니다.

Claude Desktop을 완전히 종료하고 다시 엽니다. (창을 닫는 것만으로는 충분하지 않으며, MCP 프로세스가 계속 실행됩니다.)
새 채팅에서 🛠️ / 도구 아이콘을 클릭합니다. 7개의 도구가 포함된 network-mcp-server가 나열되어야 합니다.

상호 작용 예시

연결되면 다음 프롬프트를 시도해 보십시오:

"어떤 장치에 연결되어 있나요? 호스트 이름, 모델, IOS 버전을 알려주세요." 에이전트가 get_device_info를 호출합니다.

"현재 IP 주소가 할당된 모든 인터페이스를 나열하세요." 에이전트가 get_interfaces를 호출하고 결과를 필터링합니다.

"기본 경로(default route)를 보여주세요." 에이전트가 get_routes를 호출하고 네트워크 0.0.0.0인 항목을 선택합니다.

"GigabitEthernet2의 설명을 'managed by MCP demo'로 설정하고 변경 사항이 적용되었는지 확인하세요." 에이전트가 configure_interface_description을 호출한 다음, (선택적으로) section='interface GigabitEthernet2'와 함께 get_running_config를 호출하여 이중 확인합니다.

"실행 구성을 시작 구성으로 저장하세요." 에이전트가 save_config를 호출합니다.

필요한 권한

MCP 서버는 다음이 필요합니다:

호스트 머신에서 장치의 SSH 포트(기본값 TCP/22)로의 네트워크 송신(egress). 기업 네트워크에서는 VPN이나 프록시가 필요할 수 있습니다.
privileged exec 권한이 있는 장치 계정 — DevNet 샌드박스의 admin 계정은 이미 enable 레벨입니다. 자신의 장치를 사용하는 경우, 계정은 config t에 진입하고 write memory를 실행할 수 있어야 합니다.
.env 파일 또는 Claude Desktop에 의해 설정된 동등한 환경 변수에 대한 로컬 읽기 액세스.

서버는 워크스테이션에 대한 루트/관리자 권한이 필요하지 않습니다.

보안 참고 사항

자격 증명은 하드코딩되지 않습니다. 환경 변수(DEVICE_USERNAME, DEVICE_PASSWORD)에서 가져옵니다. 필수 환경 변수가 누락되면 서버는 연결을 거부하고 명확한 오류를 반환합니다.
.env는 git-ignored 처리됩니다. 대신 .env.example(공유 가능한 DevNet 샌드박스 값 포함)이 제공됩니다.
모든 도구에 대한 입력 유효성 검사. 인터페이스 이름, 설명 및 구성 섹션 필터는 장치 CLI에 도달하기 전에 모두 정규식(regex)으로 검증됩니다. 셸 메타 문자(;, |, 백틱, 줄 바꿈, null 바이트)는 거부됩니다.
자격 증명은 도구 인수로 노출되지 않습니다. LLM은 이를 읽거나, 기록하거나, 유출할 수 없으며 도구 출력만 볼 수 있습니다.
쓰기 도구에는 검증이 포함됩니다. configure_interface_description은 변경 사항을 적용한 후 구성을 다시 읽고 applied: true/false를 보고합니다.
범위가 좁습니다. 두 개의 쓰기 도구는 인터페이스 설명 변경 및 구성 저장만 가능합니다. 파괴적인 작업(종료, IP 주소 변경, VLAN 삭제, erase startup-config)은 의도적으로 노출되지 않습니다.

문제 해결

"Missing required environment variable(s)" DEVICE_HOST / DEVICE_USERNAME / DEVICE_PASSWORD 설정을 잊었습니다. .env.example을 .env로 복사하거나 Claude Desktop의 env 블록에 설정하십시오.

"Authentication to failed" 비밀번호를 다시 확인하십시오. 샌드박스를 변경했거나 다른 장치를 사용하는 경우, SSH가 활성화되어 있고 계정에 privileged-exec 액세스 권한이 있는지 확인하십시오.

"Connection to timed out" 네트워크 송신이 차단되었습니다. 동일한 머신에서 ssh admin@sandbox-iosxe-latest-1.cisco.com을 시도해 보십시오. 이 작업도 중단되면 방화벽/VPN 문제입니다.

구성을 편집한 후 Claude Desktop에 서버가 표시되지 않음 Claude Desktop을 완전히 종료(창만 닫지 마십시오)하고 다시 여십시오. macOS: Cmd+Q. Windows: 트레이 아이콘 우클릭 → 종료.

도구 호출이 파싱된 JSON 대신 원시 텍스트를 반환함 Netmiko의 TextFSM 템플릿이 장치 출력(다른 IOS 버전, 다른 플랫폼)과 일치하지 않음을 의미합니다. 서버는 {"raw": "..."} 내의 원시 CLI 텍스트로 대체합니다. 에이전트는 여전히 이를 추론할 수 있지만 구조화되어 있지는 않습니다.

Network MCP Server