SysOM MCP is a diagnostic toolset based on the Model Context Protocol. It aggregates multiple diagnostic services into a unified interface, supports stdio and SSE modes, and can integrate with AI Assistants like Qwen Code for intelligent system analysis.-Alibaba Cloud Linux(Alinux)-阿里云帮助中心

SysOM MCP is a diagnostic toolset based on the Model Context Protocol (MCP). It consolidates multiple SysOM diagnostic services into a single MCP Server and exposes them through a standard MCP interface. You can then run these services directly or integrate them with an AI Assistant, such as Qwen Code, to perform system diagnosis, performance analysis, and troubleshooting using natural language.

Key features

Diagnosis item	Diagnosis name	Description
Memory	Memory Panorama Analysis	Use Memory Panorama Analysis when memory usage is high, but the cause is unknown.
	Java Memory Diagnosis	Merges application-layer (JVM) and operating system memory views to help you quickly find the root cause of unexpected memory usage and OOMKilled events in containerized Java applications.
	OOM Diagnosis	The Out of Memory (OOM) diagnosis feature identifies the causes of OOM events at the operating system level.
IO	I/O Traffic Analysis	I/O Traffic Analysis identifies the source of I/O traffic and is typically used to resolve IO Burst issues.
IO	One-Click I/O Diagnosis	This tool diagnoses common I/O issues, such as high latency, IO Burst, and I/O wait. It uses specialized sub-tools to analyze I/O data, provide a diagnosis, and recommend solutions for I/O-related problems.
Network	Network Packet Loss Diagnosis	Network Packet Loss Diagnosis analyzes kernel-level packet loss during network transmission and suggests solutions.
Network	Network Jitter Diagnosis	Helps you determine the cause of network jitter on an ECS Instance.
Scheduling	Scheduling Jitter Diagnosis	Scheduling Jitter Diagnosis analyzes jitter caused by prolonged delays in CPU task switching, which prevents user-space processes from being scheduled. This can occur in scenarios like memory reclamation.
Scheduling	System Load Diagnosis	System Load Diagnosis analyzes the cause of an abnormal one-minute average system load (the `load1` metric) and provides recommendations.
Crash	Crash Diagnosis	Analyzes the cause of a system crash by examining system logs and dump files.

Procedure

Prerequisites

Python 3.11+
The uv package management tool

Qwen Code requires Node.js and npm.

Installation

git clone https://github.com/alibaba/sysom_mcp.git # Clone the project
cd sysom_mcp
curl -LsSf https://astral.sh/uv/install.sh | sh  # Install uv
uv sync                                          # Install dependencies

Configure authentication

Create a .env file in the project root directory. The default authentication method is AccessKey:

type='access_key'
ACCESS_KEY_ID=your_access_key_id
ACCESS_KEY_SECRET=your_access_key_secret

For other authentication methods, such as STS or RAM Role ARN, refer to the ENV_CONFIG.md file in the project.

Start the SysOM MCP Server

SysOM MCP supports two running modes: stdio and SSE.

stdio mode (MCP Standard: JSON-RPC over stdio)
Use this mode when an MCP Client launches and manages the MCP Server, communicating via standard input and output (stdio). For example, this is the mode used when integrating with an AI Assistant:
```
uv run python sysom_main_mcp.py --stdio
```
SSE mode (HTTP/SSE Service)
Use this mode to expose the service as a network endpoint:
```
uv run python sysom_main_mcp.py --sse --host 0.0.0.0 --port 7140
```

Important considerations

Key security

The MCP Server uses an AccessKey to call Alibaba Cloud OpenAPI at runtime. The server does not store your AccessKey or use it for any purpose other than its intended diagnostic functions.

Access control

When accessing the MCP Server via the Server-Sent Events (SSE) protocol, you are responsible for securing the service endpoint.
We strongly recommend deploying the MCP Server in an internal network or a trusted environment, such as your Virtual Private Cloud (VPC). Avoid exposing it directly to the public internet.
Never expose an MCP Server SSE endpoint configured with an AccessKey to the public internet without proper access controls. This poses a significant security risk.

AI assistant integration

This section demonstrates how to integrate SysOM MCP with an AI Assistant like Qwen Code. This integration allows you to describe a problem in natural language, and the AI Assistant determines which tools to use and how to combine their outputs to provide a diagnosis.

Install Qwen Code. With Node.js and npm installed on your local machine, run the following commands:

# Optional: Configure an npm mirror source for faster downloads
npm config set registry https://registry.npmmirror.com

# Install Qwen Code
npm install -g @qwen-code/qwen-code@latest

Refer to the Alibaba Cloud Bailian documentation to activate the service and obtain the API Key and API Host.
Configure the Qwen Code MCP Server. Edit the Qwen Code configuration file, typically located at ~/.qwen/settings.json, and add SysOM MCP as an MCP Server:
```
{
  "mcpServers": {
    "sysom_mcp": {
      "command": "uv",
      "args": ["run", "python", "sysom_main_mcp.py", "--stdio"],
      "env": {
        "ACCESS_KEY_ID": "your_access_key_id",
        "ACCESS_KEY_SECRET": "your_access_key_secret",
        "DASHSCOPE_API_KEY": "your_dashscope_api_key"
      },
      "cwd": "<path_to_your_project_directory>",
      "timeout": 30000,
      "trust": false
    }
  }
}
```
Configuration details:
- command/args: Allows Qwen Code to automatically launch the SysOM MCP server and communicate with it via stdio mode.
- cwd: Set this to the root directory of your sysom_mcp project.
- env: Provide your credentials as environment variables.
- trust=false: Requires you to manually confirm that you trust this MCP Server on first use.
- timeout: The default is 30 seconds. Adjust this value based on your typical diagnostic time.