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.
# Clone the repository git clone https://github.com/apache/skywalking-mcp.git cd skywalking-mcp && go mod tidy # Build the project make
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 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) -v, --version version for swmcp 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}' # or use SSE server bin/swmcp sse --sse-address localhost:8000 --base-path /mcp --sw-url http://localhost:12800
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.{ "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" ] } } }
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. |
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) |
dev-subscribe@skywalking.apache.org, follow the reply to subscribe the mail list.skywalking channel at Apache Slack. If the link is not working, find the latest one at Apache INFRA WIKI.