Apache SkyWalking MCP

SkyWalking-MCP: A Model Context Protocol (MCP) server for integrating AI agents with Skywalking OAP and the surrounding ecosystem.

SkyWalking: an APM(application performance monitor) system, especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures.

Usage

From Source

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

# Build the project
make

Command-line Options

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.

You could start the MCP server with the following command:

# 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"

Transport URL behavior:

• stdio, sse, and streamable all use the configured --sw-url value (or the default http://localhost:12800/graphql).
• sse and streamable ignore request-level URL override headers.

Reverse proxies

The HTTP transports reject a request that arrives over a loopback address while carrying a non-loopback Host header, answering 403 Forbidden: invalid Host header. This is DNS rebinding protection: a malicious page can point its own hostname at 127.0.0.1 to reach a server running on the visitor's machine, and such a request is indistinguishable from a legitimate one except for that Host.

A same-host reverse proxy that forwards to 127.0.0.1 while preserving the public Host produces the same shape and is rejected too. Prefer having the proxy rewrite Host to localhost, or point it at a non-loopback address.

When you do opt out, pair it with --allowed-origins. A browser on the proxy host reaches 127.0.0.1 just as the proxy does, so the origin allowlist is the only defense left:

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

Disabling the protection while leaving CORS open (the default) lets any web page drive the server through the browser of anyone on that host.

Usage with Cursor, Copilot, Claude Code

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

If using Docker:

make build-image builds a local linux/amd64 image by default. For multi-platform publishing, use make docker-push, which builds and pushes linux/amd64,linux/arm64 images via Docker Buildx.

Common variants:

# 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

Then configure the MCP server like this:

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

Available Tools

SkyWalking MCP provides the following tools to query and analyze SkyWalking OAP data:

Category	Tool Name	Description
Trace	query_traces	Query traces with multi-condition filtering (service, endpoint, state, tags, and time range via start/end/step). Supports full, summary, and errors_only views with performance insights.
Log	query_logs	Query logs with filters for service, instance, endpoint, trace ID, tags, and time range. Supports cold storage and pagination.
MQE	execute_mqe_expression	Execute MQE (Metrics Query Expression) to query and calculate metrics data. Supports calculations, aggregations, TopN, trend analysis, and multiple result types.
MQE	list_mqe_metrics	List available metrics for MQE queries. Filter by regex pattern; returns metric name, type, and catalog.
MQE	get_mqe_metric_type	Get type information (REGULAR_VALUE, LABELED_VALUE, SAMPLED_RECORD) for a specific metric to help build correct MQE expressions.
Metadata	list_layers	List all layers registered in SkyWalking OAP (e.g. GENERAL, MESH, K8S).
Metadata	list_services	List all services registered in SkyWalking OAP under a specific layer.
Metadata	list_instances	List all instances of a service (e.g. pods or JVM processes).
Metadata	list_endpoints	List endpoints of a service with optional keyword filtering.
Metadata	list_processes	List processes of a service instance.
Event	query_events	Query events (deployments, restarts, scaling) with filters for service, instance, endpoint, type, and layer.
Alarm	query_alarms	Query alarms triggered by metric threshold breaches. Filter by scope, keyword, and tags.
Topology	query_services_topology	Query global or scoped service topology. Optionally filter by specific service IDs or layer.
Topology	query_instances_topology	Query service instance topology between a client service and a server service.
Topology	query_endpoints_topology	Query endpoint dependency topology for a given endpoint.
Topology	query_processes_topology	Query process topology for a given service instance.

Available Prompts

SkyWalking MCP provides the following prompts for guided analysis workflows:

Category	Prompt Name	Description	Arguments
Performance	analyze-performance	Analyze service performance using metrics tools	service_name (required), start (optional), end (optional)
Performance	compare-services	Compare performance metrics between multiple services	services (required), metrics (optional), start (optional), end (optional)
Performance	top-services	Find top N services ranked by a given metric	metric_name (required), top_n (optional), order (optional)
Trace	investigate-traces	Investigate traces for errors and performance issues	service_id (optional), trace_state (optional), start (optional), end (optional)
Trace	trace-deep-dive	Deep dive analysis of a specific trace	trace_id (required), view (optional)
Log	analyze-logs	Analyze service logs for errors and patterns	service_id (optional), log_level (optional), start (optional), end (optional)
Topology	explore-service-topology	Explore services, instances, endpoints, and processes within a layer and time range	layer (required), start (required), end (optional)
MQE	build-mqe-query	Help build MQE expressions for complex metric queries	query_type (required), metrics (required), conditions (optional)
MQE	explore-metrics	Explore available metrics and their types	pattern (optional), show_examples (optional)
Utility	generate_duration	Convert a natural-language time range into a {start, end} duration object for use with other tools	time_range (required)

Contact Us

• Submit an issue by using MCP as title prefix.
• Mail list: dev@skywalking.apache.org. Mail to dev-subscribe@skywalking.apache.org, follow the reply to subscribe the mail list.
• Join skywalking channel at Apache Slack. If the link is not working, find the latest one at Apache INFRA WIKI.
• Twitter, ASFSkyWalking

License

Apache 2.0 License.