Skywalking Mcp

Apache SkyWalking MCP ==========

SkyWalking-MCP: A [Model Context Protocol][mcp] (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.

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.

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.

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 (REGULARVALUE, LABELEDVALUE, 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.](/LICENSE)

[mcp]: https://modelcontextprotocol.io/

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: apache
• Source: apache/skywalking-mcp
• License: Apache-2.0
• Homepage: https://skywalking.apache.org/

Install and usage instructions live in the source repository linked above.