Apache SkyWalking MCP

Un servidor MCP para integrar agentes de IA con la plataforma de observabilidad SkyWalking y su ecosistema.

GitHub
37
Prueba este MCPPatrocinado

Documentación

Apache SkyWalking MCP

Sky Walking logo

SkyWalking-MCP: Un servidor Model Context Protocol (MCP) para integrar agentes de IA con Skywalking OAP y el ecosistema circundante.

SkyWalking: un sistema APM (monitor de rendimiento de aplicaciones), especialmente diseñado para microservicios, arquitecturas nativas de la nube y basadas en contenedores (Docker, Kubernetes, Mesos).

Uso

Desde el código fuente

# Clone the repository
git clone https://github.com/apache/skywalking-mcp.git
cd skywalking-mcp && go mod tidy

# Build the project
make

Opciones de línea de comandos

Usage:
  swmcp [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  sse         Start SSE server
  stdio       Start stdio server
  streamable  Start Streamable server

Global Flags:
  -h, --help                 help for swmcp
      --log-command          When true, log commands to the log file
      --log-file string      Path to log file
      --log-level string     Logging level (debug, info, warn, error) (default "info")
      --read-only            Restrict the server to read-only operations
      --sw-url string        Specify the OAP URL to connect to (e.g. http://localhost:12800)
      --sw-username string   Username for basic auth to SkyWalking OAP (supports ${ENV_VAR} syntax)
      --sw-password string   Password for basic auth to SkyWalking OAP (supports ${ENV_VAR} syntax)
      --sw-insecure          Skip TLS certificate verification for OAP connections (use only in development)
  -v, --version              version for swmcp

SSE-specific Flags:
      --sse-address string     Host and port for the SSE server (default "localhost:8000")
      --base-path string       Base path for the SSE server
      --allowed-origins string Comma-separated list of allowed CORS origins. Empty reflects any origin (open CORS). Use * to send the wildcard header.
      --disable-localhost-protection  Disable DNS rebinding protection (see Reverse proxies below)

Streamable-specific Flags:
      --address string         Host and port for the Streamable HTTP server (default "localhost:8000")
      --endpoint-path string   Endpoint path for the Streamable HTTP server (default "/mcp")
      --allowed-origins string Comma-separated list of allowed CORS origins. Empty reflects any origin (open CORS). Use * to send the wildcard header.
      --disable-localhost-protection  Disable DNS rebinding protection (see Reverse proxies below)

Use "swmcp [command] --help" for more information about a command.

Puedes iniciar el servidor MCP con el siguiente comando:

# use stdio server
bin/swmcp stdio --sw-url http://localhost:12800

# with basic auth (raw password)
bin/swmcp stdio --sw-url http://localhost:12800 --sw-username admin --sw-password admin

# with basic auth (password from environment variable)
bin/swmcp stdio --sw-url http://localhost:12800 --sw-username admin --sw-password '${SW_PASSWORD}'

# skip TLS verification (development only, e.g. self-signed certs)
bin/swmcp stdio --sw-url https://localhost:12800 --sw-insecure

# or use SSE server
bin/swmcp sse --sse-address localhost:8000 --base-path /mcp --sw-url http://localhost:12800

# restrict CORS to specific origins (SSE and streamable transports)
bin/swmcp streamable --sw-url http://localhost:12800 --allowed-origins "http://localhost:3000,https://app.example.com"

Comportamiento de la URL de transporte:

  • stdio, sse y streamable utilizan el valor de --sw-url configurado (o el valor predeterminado http://localhost:12800/graphql).
  • sse y streamable ignoran los encabezados de anulación de URL a nivel de solicitud.

Proxies inversos

Los transportes HTTP rechazan una solicitud que llega a través de una dirección de bucle local mientras lleva un encabezado Host que no es de bucle local, respondiendo 403 Forbidden: invalid Host header. Esto es protección contra el rebinding de DNS: una página maliciosa puede apuntar su propio nombre de host a 127.0.0.1 para alcanzar un servidor que se ejecuta en la máquina del visitante, y dicha solicitud es indistinguible de una legítima excepto por ese Host.

Un proxy inverso en el mismo host que reenvía a 127.0.0.1 mientras conserva el Host público produce la misma forma y también se rechaza. Prefiere que el proxy reescriba Host a localhost, o apúntalo a una dirección que no sea de bucle local.

Cuando optes por desactivarlo, combínalo con --allowed-origins. Un navegador en el host del proxy alcanza 127.0.0.1 igual que el proxy, por lo que la lista de permitidos de origen es la única defensa restante:

bin/swmcp streamable --sw-url http://localhost:12800 \
  --disable-localhost-protection --allowed-origins https://mcp.example.com

Deshabilitar la protección mientras se deja CORS abierto (el valor predeterminado) permite que cualquier página web controle el servidor a través del navegador de cualquier persona en ese host.

Uso con Cursor, Copilot, Claude Code

{
  "mcpServers": {
    "skywalking": {
      "command": "swmcp stdio",
      "args": [
        "--sw-url", "http://localhost:12800",
        "--sw-username", "admin",
        "--sw-password", "${SW_PASSWORD}"
      ]
    }
  }
}

Si usas Docker:

make build-image construye una imagen local linux/amd64 por defecto. Para publicación multiplataforma, usa make docker-push, que construye y publica imágenes linux/amd64,linux/arm64 mediante Docker Buildx.

Variantes comunes:

# Build a local image and load it into your Docker daemon
make build-image

# Build and push a multi-platform image to the default registry
make docker-push VERSION=0.1.0

# Push to a custom registry/repository
make docker-push IMAGE=ghcr.io/your-org/skywalking-mcp VERSION=0.1.0

# Build for a custom platform set
make docker-build PLATFORMS=linux/arm64 OUTPUT=--load

Luego configura el servidor MCP de la siguiente manera:

{
  "mcpServers": {
    "skywalking": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
		"skywalking-mcp:latest",
		"--sw-url",
		"http://localhost:12800"
      ]
    }
  }
}

Herramientas disponibles

SkyWalking MCP proporciona las siguientes herramientas para consultar y analizar datos de SkyWalking OAP:

CategoríaNombre de la herramientaDescripción
Trazaquery_tracesConsulta trazas con filtrado de múltiples condiciones (servicio, endpoint, estado, etiquetas y rango de tiempo mediante inicio/fin/paso). Admite vistas full, summary y errors_only con información de rendimiento.
Registroquery_logsConsulta registros con filtros por servicio, instancia, endpoint, ID de traza, etiquetas y rango de tiempo. Admite almacenamiento en frío y paginación.
MQEexecute_mqe_expressionEjecuta MQE (Expresión de consulta de métricas) para consultar y calcular datos de métricas. Admite cálculos, agregaciones, TopN, análisis de tendencias y múltiples tipos de resultados.
MQElist_mqe_metricsLista las métricas disponibles para consultas MQE. Filtra por patrón de expresión regular; devuelve nombre, tipo y catálogo de la métrica.
MQEget_mqe_metric_typeObtiene información de tipo (REGULAR_VALUE, LABELED_VALUE, SAMPLED_RECORD) para una métrica específica y ayudar a construir expresiones MQE correctas.
Metadatoslist_layersLista todas las capas registradas en SkyWalking OAP (por ejemplo, GENERAL, MESH, K8S).
Metadatoslist_servicesLista todos los servicios registrados en SkyWalking OAP bajo una capa específica.
Metadatoslist_instancesLista todas las instancias de un servicio (por ejemplo, pods o procesos JVM).
Metadatoslist_endpointsLista los endpoints de un servicio con filtrado opcional por palabra clave.
Metadatoslist_processesLista los procesos de una instancia de servicio.
Eventoquery_eventsConsulta eventos (implementaciones, reinicios, escalado) con filtros por servicio, instancia, endpoint, tipo y capa.
Alarmaquery_alarmsConsulta alarmas activadas por incumplimientos de umbrales de métricas. Filtra por alcance, palabra clave y etiquetas.
Topologíaquery_services_topologyConsulta la topología de servicios global o con alcance. Opcionalmente filtra por IDs de servicio específicos o capa.
Topologíaquery_instances_topologyConsulta la topología de instancias de servicio entre un servicio cliente y un servicio servidor.
Topologíaquery_endpoints_topologyConsulta la topología de dependencias de endpoints para un endpoint dado.
Topologíaquery_processes_topologyConsulta la topología de procesos para una instancia de servicio dada.

Prompts disponibles

SkyWalking MCP proporciona los siguientes prompts para flujos de trabajo de análisis guiados:

CategoríaNombre del promptDescripciónArgumentos
Rendimientoanalyze-performanceAnaliza el rendimiento del servicio usando herramientas de métricasservice_name (obligatorio), start (opcional), end (opcional)
Rendimientocompare-servicesCompara métricas de rendimiento entre múltiples serviciosservices (obligatorio), metrics (opcional), start (opcional), end (opcional)
Rendimientotop-servicesEncuentra los N mejores servicios clasificados por una métrica dadametric_name (obligatorio), top_n (opcional), order (opcional)
Trazainvestigate-tracesInvestiga trazas en busca de errores y problemas de rendimientoservice_id (opcional), trace_state (opcional), start (opcional), end (opcional)
Trazatrace-deep-diveAnálisis profundo de una traza específicatrace_id (obligatorio), view (opcional)
Registroanalyze-logsAnaliza registros de servicio en busca de errores y patronesservice_id (opcional), log_level (opcional), start (opcional), end (opcional)
Topologíaexplore-service-topologyExplora servicios, instancias, endpoints y procesos dentro de una capa y rango de tiempolayer (obligatorio), start (obligatorio), end (opcional)
MQEbuild-mqe-queryAyuda a construir expresiones MQE para consultas de métricas complejasquery_type (obligatorio), metrics (obligatorio), conditions (opcional)
MQEexplore-metricsExplora métricas disponibles y sus tipospattern (opcional), show_examples (opcional)
Utilidadgenerate_durationConvierte un rango de tiempo en lenguaje natural en un objeto de duración {start, end} para usar con otras herramientastime_range (obligatorio)

Contacto

Licencia

Licencia Apache 2.0.