Content
Apache SkyWalking MCP
==========
<img src="http://skywalking.apache.org/assets/logo.svg" alt="Sky Walking logo" height="90px" align="right" />
**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
```bash
# 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
```bash
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:
```bash
# 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
```json
{
"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:
```bash
# 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:
```json
{
"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](https://github.com/apache/skywalking/issues/new) 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](http://s.apache.org/slack-invite). If the link is not working, find the
latest one at [Apache INFRA WIKI](https://cwiki.apache.org/confluence/display/INFRA/Slack+Guest+Invites).
* Twitter, [ASFSkyWalking](https://twitter.com/ASFSkyWalking)
## License
[Apache 2.0 License.](/LICENSE)
[mcp]: https://modelcontextprotocol.io/
