Servidor MCP para SuzieQ

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) que permite que los modelos de lenguaje y otros clientes MCP interactúen con una instancia de observabilidad de red SuzieQ a través de su API REST.

Descripción general

El servidor expone los comandos de SuzieQ como herramientas MCP:

• run_suzieq_show : Acceda al comando 'show' para consultar tablas detalladas del estado de la red

• run_suzieq_summarize : Acceda al comando 'summarize' para obtener estadísticas agregadas y resúmenes

Estas herramientas permiten a los clientes (como Claude Desktop) consultar varias tablas de estado de red (por ejemplo, interfaces, BGP, rutas) y aplicar filtros, recuperando los resultados directamente de su instancia de SuzieQ.

Related MCP server: OpsLevel MCP

Prerrequisitos

• Python: se recomienda la versión 3.8 o superior.

• uv: Un instalador y solucionador rápido de paquetes de Python. ( Guía de instalación )

• Instancia de SuzieQ: una instancia de SuzieQ en ejecución con su API REST habilitada y accesible.

• Punto final y clave de API de SuzieQ: necesita la URL para la API de SuzieQ (por ejemplo, http://your-suzieq-host:8000/api/v2 ) y una clave de API válida ( access_token ).

Instalación y configuración

Instalación mediante herrería

Para instalar suzieq-mcp para Claude Desktop automáticamente a través de Smithery :

npx -y @smithery/cli install @PovedaAqui/suzieq-mcp --client claude

Instalación manual

1. Obtenga el código: Clone este repositorio o descargue los archivos main.py y server.py en un directorio de proyecto dedicado.

2. Crear entorno virtual: navegue al directorio de su proyecto en la terminal y cree un entorno virtual usando uv :

   uv venv

3. Activar entorno:

   • En macOS/Linux:

     source .venv/bin/activate

   • En Windows:

     GXP4 (debería ver (.venv) antes de su mensaje)

4. Instalar dependencias: Instale los paquetes de Python necesarios usando uv :

   uv pip install mcp httpx python-dotenv

   • mcp : El SDK del protocolo de contexto de modelo.

   • httpx : un cliente HTTP asincrónico utilizado para comunicarse con la API de SuzieQ.

   • python-dotenv : se utiliza para cargar variables de entorno desde un archivo .env para la configuración.

Configuración

El servidor necesita el punto final de la API de SuzieQ y su clave API. Use un archivo .env para una configuración segura y sencilla:

1. Cree un archivo .env : en la raíz del directorio de su proyecto (el mismo lugar que main.py ), cree un archivo llamado .env .

2. Agregar credenciales: Agregue su punto final y clave de SuzieQ al archivo .env . Asegúrese de que los valores no estén entre comillas, a menos que formen parte de la clave o el punto final.

   # .env
   SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2
   SUZIEQ_API_KEY=your_actual_api_key

   Reemplace los valores de marcador de posición con su punto final y clave reales.

3. Archivo .env seguro: agregue .env a su archivo .gitignore para evitar confirmar secretos accidentalmente.

   echo ".env" >> .gitignore

4. Integración de código: el server.py proporcionado.py utiliza automáticamente python-dotenv para cargar estas variables cuando se inicia el servidor.

Ejecución del servidor

Asegúrese de que su entorno virtual esté activado. El servidor cargará la configuración desde el archivo .env en el directorio actual.

1. Directamente

Ejecute el servidor directamente desde su terminal:

uv run python main.py

El servidor se iniciará, mostrará el mensaje " Starting SuzieQ MCP Server... y escuchará las conexiones MCP en la entrada/salida estándar (stdio). Debería ver los registros [INFO] si consulta correctamente la API a través de la herramienta. Presione Ctrl+C para detenerlo.

2. Con MCP Inspector (para depuración)

El Inspector MCP es útil para probar la herramienta directamente. Si tiene instaladas las herramientas CLI de mcp (mediante uv pip install "mcp[cli]" ), ejecute:

uv run mcp dev main.py

Esto inicia un depurador interactivo. Vaya a la pestaña "Herramientas", seleccione run_suzieq_show , introduzca los parámetros (p. ej., tabla: "dispositivo") y haga clic en "Llamar a la herramienta" para realizar la prueba.

Uso con Claude Desktop

Integre el servidor con Claude Desktop para un uso perfecto:

1. Busque Claude Desktop Config: localice el archivo claude_desktop_config.json .

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Ventanas: %APPDATA%\Claude\claude_desktop_config.json

   • Crea el archivo y el directorio Claude si no existen.

2. Editar archivo de configuración: Agregar una entrada para este servidor. Usar la ruta absoluta a main.py El servidor carga los secretos desde .env , por lo que no es necesario que estén en esta configuración.

{
  "mcpServers": {
    "suzieq-server": {
      // Use 'uv' if it's in the system PATH Claude uses,
      // otherwise provide the full path to the uv executable.
      "command": "uv",
      "args": [
        "run",
        "python",
        // --- VERY IMPORTANT: Use the ABSOLUTE path below ---
        "/full/path/to/your/project/mcp-suzieq-server/main.py"
      ],
      // 'env' block is not needed here if .env is in the project directory above
      "workingDirectory": "/full/path/to/your/project/mcp-suzieq-server/" // Optional, but recommended
    }
    // Add other servers here if needed
  }
}

• Reemplace /full/path/to/your/project/mcp-suzieq-server/main.py con la ruta absoluta correcta en su sistema.

• Reemplace /full/path/to/your/project/mcp-suzieq-server/ con la ruta absoluta al directorio que contiene main.py y .env . Configurar workingDirectory ayuda a garantizar que se encuentre el archivo .env .

• Si Claude no encuentra uv , reemplace "uv" con su ruta absoluta (buscar mediante which uv o where uv ).

• En Windows, es posible que necesite "env": { "PYTHONUTF8": "1" } si encuentra problemas de codificación de texto.

3. Reiniciar Claude Desktop: cierre completamente y vuelva a abrir Claude Desktop.

4. Verificar: Busca el indicador de la herramienta MCP (icono del martillo 🔨) en Claude Desktop. Al hacer clic en él, deberían aparecer las herramientas run_suzieq_show y run_suzieq_summarize .

Uso de herramientas (run_suzieq_show)

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str

• tabla : (cadena, obligatoria) El nombre de la tabla SuzieQ (por ejemplo, "dispositivo", "interfaz", "bgp").

• Filtros : (Diccionario, Opcional) Pares clave-valor para filtrar (p. ej., "hostname": "leaf01" ). Omitir o usar {} para no aplicar filtros.

• Devuelve : una cadena JSON con los resultados o un error.

Ejemplos de invocaciones (conceptuales):

Mostrar todos los dispositivos:

{ "table": "device" }

Mostrar vecinos BGP para el nombre de host 'spine01':

{ "table": "bgp", "filters": { "hostname": "spine01" } }

Mostrar interfaces 'activas' en VRF 'predeterminado':

{ "table": "interface", "filters": { "vrf": "default", "state": "up" } }

Uso de la herramienta (run_suzieq_summarize)

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str

• tabla : (cadena, obligatoria) El nombre de la tabla SuzieQ para resumir (por ejemplo, "dispositivo", "interfaz", "bgp").

• Filtros : (Diccionario, Opcional) Pares clave-valor para filtrar (p. ej., "hostname": "leaf01" ). Omitir o usar {} para no aplicar filtros.

• Devuelve : una cadena JSON con los resultados resumidos o un error.

Ejemplos de invocaciones (conceptuales):

Resumir todos los dispositivos:

{ "table": "device" }

Resumir las sesiones BGP por nombre de host 'spine01':

{ "table": "bgp", "filters": { "hostname": "spine01" } }

Resumir los estados de la interfaz en VRF 'predeterminado':

{ "table": "interface", "filters": { "vrf": "default" } }

Solución de problemas

Error: "Punto final o clave de la API de SuzieQ no configurado..."

• Asegúrese de que el archivo .env esté en el mismo directorio que main.py

• Verifique SUZIEQ_API_ENDPOINT y SUZIEQ_API_KEY estén escritos correctamente y tengan valores válidos en .env .

• Si usa Claude Desktop, asegúrese de que el workingDirectory en claude_desktop_config.json apunte al directorio que contiene .env .

Errores HTTP (4xx, 5xx):

• Compruebe que la clave API de SuzieQ ( SUZIEQ_API_KEY ) sea correcta (errores 401/403).

• Verifique que SUZIEQ_API_ENDPOINT sea correcto y que el servidor API esté ejecutándose.