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

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)
  -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

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

Usage with Cursor

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

If using Docker:

make build-image to build the Docker image, then configure the MCP server like this:

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

Available Tools

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

Category	Tool Name	Description	Key Features
Trace	`get_trace_details`	Get detailed trace information	Retrieve trace by ID; Multiple views: `full` (complete trace), `summary` (overview with metrics), `errors_only` (error spans only); Detailed span analysis
Trace	`get_cold_trace_details`	Get trace details from cold storage	Query historical traces from BanyanDB; Multiple views: `full`, `summary`, `errors_only`; Duration-based search; Historical incident investigation
Trace	`query_traces`	Query traces with intelligent analysis	Multi-condition filtering (service, endpoint, duration, state, tags); Multiple views: `full` (raw data), `summary` (intelligent analysis with performance insights), `errors_only` (error traces); Sort options; Slow trace detection; Performance metrics and statistics
Metrics	`query_single_metrics`	Query single metric values	Get specific metric values (CPM, response time, SLA, Apdex); Multiple entity scopes (Service, ServiceInstance, Endpoint, Process, Relations); Time range and cold storage support
Metrics	`query_top_n_metrics`	Query top N metric rankings	Rank entities by metric values; Configurable top N count; Ascending/descending order; Scope-based filtering; Performance analysis and issue identification
Log	`query_logs`	Query logs from SkyWalking OAP	Filter by service, instance, endpoint, trace ID, tags; Time range queries; Cold storage support; Pagination support
MQE	`execute_mqe_expression`	Execute MQE expressions for metrics	Execute complex MQE (Metrics Query Expression) queries; Support calculations, aggregations, comparisons, TopN, trend analysis; Multiple result types (single value, time series, sorted list); Entity filtering and relation metrics; Debug and tracing capabilities
MQE	`list_mqe_metrics`	List available metrics for MQE	Discover available metrics for MQE queries; Filter by regex patterns; Get metric metadata (type, catalog); Support service, instance, endpoint, relation, database, and infrastructure metrics
MQE	`get_mqe_metric_type`	Get metric type information	Get detailed type information for specific metrics; Understand metric structure (regular value, labeled value, sampled record); Help with correct MQE expression syntax

Contact Us

Submit an issue by using MCP as title prefix.
Mail list: [email protected]. Mail to [email protected], 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.