Apache SkyWalking MCP

Um servidor MCP para integrar agentes de IA com a plataforma de observabilidade SkyWalking e seu ecossistema.

GitHub
37
Experimente este MCPPatrocinado

Documentação

Apache SkyWalking MCP

Sky Walking logo

SkyWalking-MCP: Um servidor Model Context Protocol (MCP) para integrar agentes de IA com o Skywalking OAP e o ecossistema ao redor.

SkyWalking: um sistema de APM (monitoramento de desempenho de aplicações), especialmente projetado para arquiteturas de microsserviços, cloud native e baseadas em contêineres (Docker, Kubernetes, Mesos).

Uso

A partir do código-fonte

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

# Build the project
make

Opções de linha de comando

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.

Você pode iniciar o servidor MCP com o seguinte 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"

Comportamento da URL de transporte:

  • stdio, sse e streamable usam o valor configurado de --sw-url (ou o padrão http://localhost:12800/graphql).
  • sse e streamable ignoram cabeçalhos de substituição de URL em nível de solicitação.

Proxies reversos

Os transportes HTTP rejeitam uma solicitação que chega por um endereço de loopback enquanto carrega um cabeçalho Host que não seja de loopback, respondendo com 403 Forbidden: invalid Host header. Isso é proteção contra rebinding de DNS: uma página maliciosa pode apontar seu próprio nome de host para 127.0.0.1 para alcançar um servidor em execução na máquina do visitante, e tal solicitação é indistinguível de uma legítima, exceto por esse Host.

Um proxy reverso no mesmo host que encaminha para 127.0.0.1 preservando o Host público produz o mesmo formato e também é rejeitado. Prefira fazer o proxy reescrever Host para localhost, ou aponte-o para um endereço que não seja de loopback.

Quando você optar por desativar, combine com --allowed-origins. Um navegador no host do proxy alcança 127.0.0.1 exatamente como o proxy faz, então a lista de permissões de origem é a única defesa restante:

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

Desabilitar a proteção enquanto mantém o CORS aberto (o padrão) permite que qualquer página da web acione o servidor por meio do navegador de qualquer pessoa nesse host.

Uso com Cursor, Copilot, Claude Code

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

Se estiver usando Docker:

make build-image cria uma imagem local linux/amd64 por padrão. Para publicação multiplataforma, use make docker-push, que cria e envia imagens linux/amd64,linux/arm64 via Docker Buildx.

Variantes comuns:

# 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

Em seguida, configure o servidor MCP assim:

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

Ferramentas Disponíveis

O SkyWalking MCP fornece as seguintes ferramentas para consultar e analisar dados do SkyWalking OAP:

CategoriaNome da FerramentaDescrição
Tracequery_tracesConsulta traces com filtragem por múltiplas condições (serviço, endpoint, estado, tags e intervalo de tempo via início/fim/etapa). Suporta visualizações full, summary e errors_only com insights de desempenho.
Logquery_logsConsulta logs com filtros para serviço, instância, endpoint, ID de trace, tags e intervalo de tempo. Suporta armazenamento frio e paginação.
MQEexecute_mqe_expressionExecuta MQE (Metrics Query Expression) para consultar e calcular dados de métricas. Suporta cálculos, agregações, TopN, análise de tendências e múltiplos tipos de resultado.
MQElist_mqe_metricsLista métricas disponíveis para consultas MQE. Filtra por padrão regex; retorna nome da métrica, tipo e catálogo.
MQEget_mqe_metric_typeObtém informações de tipo (REGULAR_VALUE, LABELED_VALUE, SAMPLED_RECORD) para uma métrica específica, ajudando a construir expressões MQE corretas.
Metadatalist_layersLista todas as camadas registradas no SkyWalking OAP (ex.: GENERAL, MESH, K8S).
Metadatalist_servicesLista todos os serviços registrados no SkyWalking OAP sob uma camada específica.
Metadatalist_instancesLista todas as instâncias de um serviço (ex.: pods ou processos JVM).
Metadatalist_endpointsLista endpoints de um serviço com filtragem opcional por palavra-chave.
Metadatalist_processesLista processos de uma instância de serviço.
Eventquery_eventsConsulta eventos (implantações, reinicializações, escalonamento) com filtros para serviço, instância, endpoint, tipo e camada.
Alarmquery_alarmsConsulta alarmes acionados por violações de limite de métricas. Filtra por escopo, palavra-chave e tags.
Topologyquery_services_topologyConsulta topologia de serviços global ou com escopo. Opcionalmente, filtra por IDs de serviço específicos ou camada.
Topologyquery_instances_topologyConsulta topologia de instâncias de serviço entre um serviço cliente e um serviço servidor.
Topologyquery_endpoints_topologyConsulta topologia de dependência de endpoints para um endpoint específico.
Topologyquery_processes_topologyConsulta topologia de processos para uma instância de serviço específica.

Prompts Disponíveis

O SkyWalking MCP fornece os seguintes prompts para fluxos de trabalho de análise guiada:

CategoriaNome do PromptDescriçãoArgumentos
Desempenhoanalyze-performanceAnalisa o desempenho do serviço usando ferramentas de métricasservice_name (obrigatório), start (opcional), end (opcional)
Desempenhocompare-servicesCompara métricas de desempenho entre vários serviçosservices (obrigatório), metrics (opcional), start (opcional), end (opcional)
Desempenhotop-servicesEncontra os N principais serviços classificados por uma determinada métricametric_name (obrigatório), top_n (opcional), order (opcional)
Traceinvestigate-tracesInvestiga traces para erros e problemas de desempenhoservice_id (opcional), trace_state (opcional), start (opcional), end (opcional)
Tracetrace-deep-diveAnálise aprofundada de um trace específicotrace_id (obrigatório), view (opcional)
Loganalyze-logsAnalisa logs de serviço para erros e padrõesservice_id (opcional), log_level (opcional), start (opcional), end (opcional)
Topologiaexplore-service-topologyExplora serviços, instâncias, endpoints e processos dentro de uma camada e intervalo de tempolayer (obrigatório), start (obrigatório), end (opcional)
MQEbuild-mqe-queryAjuda a construir expressões MQE para consultas de métricas complexasquery_type (obrigatório), metrics (obrigatório), conditions (opcional)
MQEexplore-metricsExplora métricas disponíveis e seus tipospattern (opcional), show_examples (opcional)
Utilitáriogenerate_durationConverte um intervalo de tempo em linguagem natural em um objeto de duração {start, end} para uso com outras ferramentastime_range (obrigatório)

Contato

Licença

Licença Apache 2.0.