Cisco NSO MCP Server

Servidor MCP Cisco NSO

Uma implementação de servidor Model Context Protocol (MCP) para Cisco NSO (Network Services Orchestrator) que expõe dados e operações do NSO como primitivas MCP (Tools, Resources, etc.) que podem ser consumidas por um cliente compatível com MCP, permitindo automação de rede com IA por meio de interações em linguagem natural.

Exemplo de Cliente Personalizado

O que é MCP?

Model Context Protocol (MCP) é um protocolo aberto que padroniza como modelos de IA interagem com ferramentas e serviços externos. MCP permite:

• Definição de Ferramentas: Forma estruturada de definir ferramentas que modelos de IA podem usar
• Descoberta de Ferramentas: Mecanismo para modelos descobrirem ferramentas disponíveis
• Execução de Ferramentas: Método padronizado para modelos chamarem ferramentas e receberem resultados
• Gerenciamento de Contexto: Passagem eficiente de contexto entre ferramentas e modelos
• Independente de Framework: Funciona em múltiplos frameworks de IA, incluindo OpenAI, Anthropic, Google Gemini e outros
• Interoperabilidade: Fornece uma linguagem comum para sistemas de IA se comunicarem com ferramentas externas

Recursos

• Transporte Stdio: Por padrão, este servidor MCP usa transporte stdio para comunicação baseada em processos
• Design Focado em Ferramentas: Operações de rede são definidas como ferramentas discretas com interfaces claras
• Processamento Assíncrono: Todas as operações de rede são implementadas de forma assíncrona para melhor desempenho
• Respostas Estruturadas: Formato de resposta consistente com seções de status, dados e metadados
• Recursos de Ambiente: Fornece informações contextuais sobre o ambiente NSO
• Integração NSO: Usa a biblioteca cisco-nso-restconf para uma interface limpa e Pythonic com a API RESTCONF do NSO
• Logging Flexível: Logging configurável para stdout e/ou arquivo por meio de variáveis de ambiente. Quando a variável de ambiente LOG_FILE está definida, os logs são enviados tanto para stdout quanto para o arquivo especificado. Se o arquivo de log não puder ser criado ou gravado, o servidor volta para logging somente em stdout com uma mensagem de erro
• Suporte a Múltiplos Clientes: Funciona com qualquer cliente compatível com MCP, incluindo Windsurf Cascade e aplicações Python personalizadas

Ferramentas e Recursos Disponíveis

Ferramentas

Nome da Ferramenta	Descrição	Entradas	Retornos
get_device_ned_ids	Recupera IDs de Network Element Driver (NED) do Cisco NSO		Um dicionário com uma lista de IDs NED
get_device_groups	Recupera grupos de dispositivos do Cisco NSO		Um dicionário com uma lista de grupos de dispositivos
get_device_platform	Obtém informações de plataforma para um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com informações de plataforma para o dispositivo especificado
get_device_config	Obtém a configuração completa para um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com a configuração para o dispositivo especificado
get_device_state	Obtém o estado para um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com o estado para o dispositivo especificado
check_device_sync	Verifica o status de sincronização para um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com o status de sincronização para o dispositivo especificado
sync_from_device	Sincroniza a partir de um dispositivo específico no Cisco NSO	'device_name' (string)	Um dicionário com o status de sincronização para o dispositivo especificado
get_service_types	Obtém tipos de serviço no Cisco NSO		Um dicionário com tipos de serviço
get_services	Obtém serviços para um tipo de serviço específico no Cisco NSO	'service_type' (string)	Um dicionário com serviços para o tipo de serviço especificado

Recursos

• https://resources.cisco-nso-mcp.io/environment: Fornece um resumo selecionado do ambiente NSO:
  • Contagem de dispositivos, Distribuição de Sistema Operacional, Contagem de Sistemas Operacionais Únicos, Contagem de Modelos Únicos, Distribuição de Modelos, Distribuição de Séries de Dispositivos, Grupos de Dispositivos e Membros

Requisitos

• Python 3.12+
• Cisco NSO com API RESTCONF habilitada
• Conectividade de rede com a API RESTCONF do NSO

Opções de Configuração

Você pode configurar o servidor usando argumentos de linha de comando ou variáveis de ambiente:

Parâmetros de Conexão NSO

Argumento de Linha de Comando	Variável de Ambiente	Padrão	Descrição
--nso-scheme	NSO_SCHEME	http	Esquema de conexão NSO (http/https)
--nso-address	NSO_ADDRESS	localhost	Endereço do servidor NSO
--nso-port	NSO_PORT	8080	Porta do servidor NSO
--nso-timeout	NSO_TIMEOUT	10	Tempo limite de conexão em segundos
--nso-username	NSO_USERNAME	admin	Nome de usuário NSO
--nso-password	NSO_PASSWORD	admin	Senha NSO
--nso-verify	NSO_VERIFY	True	Verificar certificado HTTPS do NSO (padrão: True). Use --no-nso-verify para certificados autoassinados (apenas desenvolvimento).
--nso-ca-bundle	NSO_CA_BUNDLE	None	Caminho para um arquivo de pacote CA para confiar no HTTPS do NSO. Aplicável quando -nso-verify é True.

Parâmetros do Servidor MCP

Argumento de Linha de Comando	Variável de Ambiente	Padrão	Descrição
--transport	MCP_TRANSPORT	stdio	Tipo de transporte MCP (stdio/http)

Opções de Transporte HTTP (usadas apenas quando --transport=http)

FastMCP HTTP Server reference: https://gofastmcp.com/deployment/http#http-deployment

Command-line Argument	Environment Variable	Default	Description
--host	MCP_HOST	0.0.0.0	Host to bind to when using HTTP transport
--port	MCP_PORT	8000	Port to bind to when using HTTP transport

Logging Configuration

Environment Variable	Default	Description
LOG_FILE	None	Path to log file. If not set, logs will be sent to stdout only

Environment variables take precedence over default values but are overridden by command-line arguments.

Connecting to the Server with MCP Clients

You can connect to the server using any MCP client that supports the selected transport type. A few options are:

Windsurf Cascade

Windsurf Cascade supports MCP servers through a configuration file. To use the Cisco NSO MCP server with Windsurf, add it to your mcp_config.json file.

Using uv (recommended)

When using uv, no specific installation is needed. You can use uvx to directly run the package:

{
  "mcpServers": {
    "nso": {
      "command": "uvx",
      "args": [
        "cisco-nso-mcp-server",
        "--nso-address=127.0.0.1",
        "--nso-port=8080",
        "--nso-username=admin",
        "--nso-password=admin"
      ],
      "env": {
        "LOG_FILE": "/path/to/your/logs/nso-mcp.log"
      }
    }
  }
}

Usando com instalação via pip

Alternativamente, você pode instalar o cisco-nso-mcp-server via pip:

pip install cisco-nso-mcp-server

Agora você pode usar o caminho direto para o executável:

{
  "mcpServers": {
    "nso": {
      "command": "/path/to/your/env/bin/cisco-nso-mcp-server",
      "args": [
        "--nso-address=127.0.0.1",
        "--nso-port=8080",
        "--nso-username=admin",
        "--nso-password=admin"
      ],
      "env": {
        "LOG_FILE": "/path/to/your/logs/nso-mcp.log"
      }
    }
  }
}

Substitua /path/to/your/env/bin/cisco-nso-mcp-server pelo caminho real onde você instalou o pacote com pip. Você pode encontrar isso executando which cisco-nso-mcp-server se o instalou em seu ambiente principal, ou localizando-o no diretório bin do seu ambiente virtual.

Em ambos os casos, a seção env é opcional. Se você a incluir, pode especificar a variável de ambiente LOG_FILE para habilitar o logging em arquivo.

Usando em um aplicativo Python de cliente MCP personalizado com transporte stdio

Um aplicativo Python de exemplo é fornecido em sample_stdio_client.py que demonstra como conectar ao servidor MCP localmente e executar uma ferramenta.

Executando o Servidor como Standalone

Embora o servidor seja normalmente usado com um cliente MCP, você também pode executá-lo diretamente como um processo standalone:

# Run with default NSO connection and MCP settings (see Configuration Options above for details)
cisco-nso-mcp-server

# Run with custom NSO connection parameters
cisco-nso-mcp-server --nso-scheme=http --nso-address=127.0.0.1 --nso-port=8080 --nso-username=admin --nso-password=admin

Ao executar como um processo standalone com transporte stdio, você precisará direcionar entrada/saída para o processo ou usá-lo com um cliente MCP que suporte transporte stdio.

Licença

Este projeto é licenciado sob a Licença MIT. Isso significa que você pode usar, modificar e distribuir o código, sujeito aos termos e condições da Licença MIT.