Packet Tracer MCP

Claude Code가 자연어로 Cisco Packet Tracer에서 토폴로지를 구축하고 구성할 수 있게 해주는 MCP 서버: 디바이스 생성, 케이블 연결, IOS 명령 적용, VLAN, OSPF, NAT, ACL, VoIP, 또는 다이어그램 이미지에서 전체 네트워크 재현까지 가능합니다.

Tu -> Claude Code --stdio--> mcp_server.py --HTTP--> bridge :54321
                                                         |
                              Packet Tracer  <-----------+
                              modulo Builder:
                                bridge.js         (pagina: hace el polling)
                                bridge_runner.js  (motor: ejecuta y devuelve)

HTTP 브리지는 MCP 서버 내부에서 실행됩니다. 별도로 터미널을 띄울 필요가 없습니다. 그리고 폴링 루프는 Builder 모듈 안에 있습니다. Packet Tracer에 붙여넣을 것도 없습니다.

요구 사항

Related MCP server: packet-tracer-mcp

시작하기(최초 1회)

1. 의존성

uv sync

2. Packet Tracer에 Builder 모듈 설치

packet_tracer/Builder.pts는 PT 내부에서 이 프로젝트가 사용하는 함수(addDevice, addLink, addModule, configureIosDevice, configurePcIp, getDevices, removeLink, addLabel, saveTopology)와 HTTP 브리지와 통신하는 브리지를 정의하는 스크립트 모듈입니다. 이 모듈이 없으면 아무것도 작동하지 않습니다.

Packet Tracer에서(영문 메뉴, PT 9.0.0에서 확인):

1. Extensions -> Scripting -> Configure PT Script Modules

2. Add -> 이 저장소의 packet_tracer/Builder.pts 선택

3. 목록에서 Builder 선택 -> Settings -> On Startup 체크. PT를 열 때마다 모듈이 자동으로 시작됩니다.

4. 실행 중인지 확인하려면: Extensions 메뉴에 Builder Code Editor 항목이 나타나야 합니다. 나타나지 않으면 모듈이 시작되지 않은 것입니다.

시작하면 모듈이 Builder Code Editor 창을 자동으로 엽니다. 이 창이 폴링 루프를 호스팅하므로 작업하는 동안 열려 있어야 합니다. 제목에 "bridge activo"라고 표시되면 브리지가 작동 중인 것입니다.

3. Claude Code에서 프로젝트 열기

프로젝트 폴더에서 터미널을 엽니다:

claude

Claude Code는 .mcp.json을 읽고 MCP 서버(그리고 함께 HTTP 브리지)를 자동으로 시작합니다. 처음에는 폴더를 신뢰하는지 확인을 요청할 수 있습니다.

서버가 연결되었는지 확인하려면 Claude Code에서 /mcp를 입력하세요. packet-tracer와 그 도구들이 표시되어야 합니다.

일상적인 사용

1. Abre Packet Tracer
   -> la ventana "Builder Code Editor" se abre sola y debe quedarse abierta

2. En una terminal, en la carpeta del proyecto:
      cd ruta/al/pt_MCP
      claude

3. Dentro de Claude Code:
      /pt-iniciar     -> confirma que las 3 piezas responden

다른 것은 시작할 필요가 없습니다: main.py도, Packet Tracer에 스크립트를 붙여넣는 것도, 추가 터미널도 필요 없습니다.

그리고 그때부터 자연어로:

• «라우터 2911 두 대를 시리얼로 10.0.0.0/30으로 연결하고 각 LAN에 PC 하나씩»

• /pt-desde-imagen diagramas/ejemplo-red1.jpeg — 다이어그램의 토폴로지 재현

• «SW1에 VLAN 10 VENTAS를 구성하고 포트 1-4를 access로 설정»

캔버스에 아무것도 나타나지 않으면 Claude에게 verificar_entorno()를 호출하라고 요청하세요. 세 가지 구성 요소 중 어떤 것이 다운되었는지, 어떻게 복구하는지 알려줍니다.

구조

packet_tracer/의 두 .js 파일은 이미 Builder.pts 안에 들어 있습니다. 저장소에 따로 있는 것은 필요할 때 읽고, 버전 관리하고, 다시 가져오기 위함입니다.

uv run python main.py는 MCP 없이 브리지만 단독으로 실행할 때도 계속 사용할 수 있습니다(디버깅 스크립트에 필요한 기능).

명령이 전달되는 방식

1. Claude가 MCP 도구를 호출하면 PT의 JS 한 줄로 변환됩니다.

2. mcp_server.py가 POST /add_command로 큐에 넣습니다.

3. Builder Code Editor 창 안의 bridge.js가 GET /next_command(2초마다)로 가져와 $se('runCodeBridge', codigo)를 호출합니다.

4. bridge_runner.js가 스크립트 엔진에서 실행하고, 값을 반환하면 evaluateJavaScriptAsync로 페이지에 다시 전달합니다.

5. 페이지가 POST /command_result로 게시하고 mcp_server.py가 수신합니다.

4단계가 필요한 이유는 $se()가 호출을 전달했다는 것만 확인할 뿐( true로 resolve) 실행된 코드의 값은 절대 반환하지 않기 때문입니다.

각 요청은 고유한 마커(a1b2c3d4|...)로 감싸져 전송되며, 그 마커를 다시 가져오는 결과만 수락됩니다. 이게 없으면 늦게 도착한 응답이 큐에 남아 다음 요청이 잘못된 응답을 받게 됩니다.

알려진 제한 사항

• Packet Tracer는 IOS 명령의 출력을 노출하지 않습니다: hacer_ping()과 obtener_tabla_routing()은 명령을 보내지만 그 출력은 PT 내부 디바이스 콘솔에서만 볼 수 있습니다. API 쿼리(getDevices(), 포트 상태)는 데이터를 반환합니다.

• crear_dispositivo(), conectar_dispositivos(), agregar_modulo_router() 및 eliminar_conexion()은 실제 결과를 확인합니다([OK] / [ERROR]). 나머지 쓰기 명령(IOS 구성)은 확인 없이 큐에 들어갑니다: Exito: Comando enviado는 실행이 아니라 큐에 들어갔다는 뜻입니다.

• 특정 디바이스를 생성하면 PT가 캔버스에 Power Distribution Device0를 자동으로 추가합니다. 인벤토리에 나타나지만 오류는 아닙니다.

• obtener_puertos_dispositivo()는 설치된 카드의 포트를 포함하여 PT의 실제 디바이스 포트를 읽고 어떤 포트가 비어 있는지 알려줍니다.

• diagnosticar_red()는 802.1Q 서브인터페이스, VLAN, 라우팅 테이블을 볼 수 없습니다. 오류를 보고하지 않는다고 해서 연결성이 보장되지는 않습니다.

• Builder Code Editor 창은 열려 있어야 합니다. 폴링 루프가 거기 있기 때문입니다.