SLS MCP Server-Simple Log Service(SLS)-阿里云帮助中心

Simple Log Service (SLS) provides an official Model Context Protocol (MCP) server that connects AI agents to your SLS resources. After you add SLS MCP Server to an agent such as Qoder or Codex, you browse projects and LogStores, query and analyze logs, and diagnose alerts by using natural language.

What you can do with SLS MCP Server

SLS MCP Server provides 11 tools in three categories. The AI agent selects the tool that matches your request, so you do not need to remember console entry points or write query statements by hand.

Resource discovery — Ask which projects and LogStores you own instead of logging on to the console and browsing them one by one.
Log query and analysis — Describe what you want to query in one sentence instead of switching between console pages. These tools cover the common log analysis path: check the index configuration, run a query, and then review the distribution over time.
Alert diagnostics — After an alert is triggered, ask the AI agent to analyze the cause and locate the problem quickly.
For the tools in each category, see the Supported tools section.

How SLS MCP Server works

Model Context Protocol (MCP) is an open standard that lets AI assistants connect to external data sources and tools in a uniform way. When a service provides an MCP server, AI assistants can use its capabilities in a Plug and Play manner.

SLS MCP Server runs on your local machine. After an AI agent connects to it, the server calls SLS OpenAPI on your behalf by using the OAuth credentials that you configured. The following diagram shows the end-to-end path.

AI agent (Qoder, Codex, and so on)
 │ MCP protocol (stdio transport)
 ▼
alibabacloud-sls-mcp-proxy (runs locally)
 │ OAuth credentials (from an Alibaba Cloud CLI profile)
 ▼
Simple Log Service (SLS) OpenAPI

Considerations

Review the following items before you connect SLS MCP Server to an AI agent:

Authentication — SLS MCP Server authenticates to SLS with OAuth credentials that are stored in an Alibaba Cloud CLI profile. You sign in through a browser, so you never create or paste an AccessKey pair.
One-time RAM authorization — Before anyone in the Alibaba Cloud account signs in with OAuth for the first time, a RAM administrator must install the official-cli application and add the RAM users or roles that use Alibaba Cloud CLI to the authorization list. For instructions, see the Grant OAuth access to Alibaba Cloud CLI section.
Region-less access — You do not need to specify the region of a project when you access it. SLS MCP Server matches the corresponding region automatically, so a single credential profile gives you cross-region access to all of your projects.
Alert tool behavior — The alert diagnostics tools are read-only and do not change the state of any alert. Masking differs by tool: sls_list_alerts returns neither query statements nor notification targets, and sls_get_alert returns diagnostic queries with sensitive notification configurations masked.

Prerequisites

An Alibaba Cloud account. If you use a Resource Access Management (RAM) user, the RAM user must have access permissions for SLS.
The uv tool installed on your local machine. SLS MCP Server is started with the uvx command, which is provided with uv. For installation instructions, see the uv documentation.

Grant OAuth access to Alibaba Cloud CLI

A RAM administrator performs the following steps once for the Alibaba Cloud account. You do not need to repeat them later. If you are not a RAM administrator, confirm with your administrator that this authorization is complete before you start the quick start.

Install the CLI application: Log on to the RAM console. In the left-side navigation pane, choose OAuth (Preview), and then click the Third-party Application tab. If the official-cli application is not listed, select Official CLI to install it.
Assign identities: Open the official-cli application details page and click the Allowed Identities tab. Click Add Users or roles to add the RAM users or roles that need to use Alibaba Cloud CLI to the authorization list.

Quick start

The following steps are performed by the user of the AI agent. They assume that the one-time OAuth authorization described in the previous section is complete.

Step 1: Install Alibaba Cloud CLI

Run the following command to install Alibaba Cloud CLI.

sudo /bin/bash -c "$(curl -fsSL https://aliyuncli.alicdn.com/install.sh)"

After the installation is complete, run aliyun version. If the command returns a version number, the installation is successful.

Step 2: Sign in with OAuth and create a credential profile

Run the following command. A browser page opens automatically. Complete the sign-in to finish authentication.

aliyun configure --mode OAuth

After the sign-in succeeds, Alibaba Cloud CLI stores the OAuth credentials in a profile. The default profile name is default. To manage multiple accounts or multiple environments, use the -p parameter to specify a custom profile name.

aliyun configure --mode OAuth -p sls-test-oauth

Note the profile name that you use. You specify it with the --profile parameter in Step 3.

Note

Enter cn-hangzhou when the CLI prompts you for a region. The region that you specify does not limit the projects that SLS MCP Server can access.

Step 3: Add SLS MCP Server to your AI agent

Complete the configuration for the client that you use. You do not need to configure more than one client. SLS MCP Server uses the standard stdio transport, so you can connect it to any AI agent that supports MCP: set the startup command to uvx and the arguments to alibabacloud-sls-mcp-proxy@latest --profile <your profile name>.

The following examples use the default profile. If you created a custom profile with the -p parameter in Step 2, replace default with that profile name.

Note

The uvx alibabacloud-sls-mcp-proxy@latest command downloads and runs the latest version of SLS MCP Server locally. Every command in this step requires uvx, which is provided with uv.

Clients that you configure with a CLI command

Qoder

# Add the MCP Server
qodercli mcp add \
  --scope user \
  --transport stdio \
  alibabacloud-sls \
  -- uvx alibabacloud-sls-mcp-proxy@latest --profile default

# List the MCP Servers that you added
qodercli mcp list

Codex

# Add the MCP Server
codex mcp add alibabacloud-sls \
  -- uvx alibabacloud-sls-mcp-proxy@latest --profile default

# List the MCP Servers that you added
codex mcp list

Claude Code

# Add the MCP Server. --scope user applies the configuration to all projects of the current user.
claude mcp add --scope user alibabacloud-sls \
  -- uvx alibabacloud-sls-mcp-proxy@latest --profile default

# List the MCP Servers that you added
claude mcp list

OpenClaw

# Add the MCP Server
openclaw mcp add alibabacloud-sls \
  --command uvx \
  --arg alibabacloud-sls-mcp-proxy@latest \
  --arg --profile \
  --arg default

# List the MCP Servers that you added
openclaw mcp list

Clients that you configure with a configuration file

Cursor, Cline, Cherry Studio, and other JSON-based clients

For clients that configure MCP servers in a JSON file, add the following content to the MCP configuration file:

{
  "mcpServers": {
    "alibabacloud-sls": {
      "command": "uvx",
      "args": [
        "alibabacloud-sls-mcp-proxy@latest",
        "--profile",
        "default"
      ]
    }
  }
}

Hermes Agent

Hermes Agent manages MCP servers in a configuration file. Edit the ~/.hermes/config.yaml file in your home directory, or create the file if it does not exist, and add the following content:

mcp_servers:
  alibabacloud-sls:
    command: uvx
    args:
      - alibabacloud-sls-mcp-proxy@latest
      - --profile
      - default

Save the file and restart Hermes Agent, or run /reload-mcp in a session to reload the MCP configuration.

Step 4: Verify the connection

Open your AI agent and enter a natural language request.

List the SLS projects that I can access

If the AI agent returns your project list, SLS MCP Server is connected. If the project list is not returned, confirm the following items:

The uvx command is available on your local machine.
The one-time OAuth authorization covers your RAM user or role.
The --profile value in the client configuration matches the profile name that you created in Step 2.

Usage examples

After you complete the connection, ask questions in natural language directly in your AI agent. The following examples show typical usage.

Example 1: Find resources

List the SLS projects that I can access in the China (Hangzhou) region

The AI agent calls sls_list_projects and returns the project list. You can then ask a follow-up question:

Which Logstores does the nginx-prod project contain?

The AI agent calls sls_list_logstores and lists the corresponding LogStores.

Example 2: Query logs

Query the logs that contain error in the access-log Logstore of the nginx-prod project over the last 1 hour

The AI agent calls sls_query_logs and automatically uses a relative time range such as now-1h to now. To understand the log volume distribution, ask a follow-up question:

Approximately how many logs are there? Show me the distribution over time

The AI agent calls sls_get_log_histogram and returns the total number of matched logs and their distribution over time.

Example 3: View the log context

A single log often does not provide enough information during troubleshooting. Ask the AI agent to retrieve the log context:

Show me the 20 log lines before and after this error log

The AI agent uses the __pack_id__ and __pack_meta__ values from the previous query result, calls sls_get_context_logs, and returns the full context before and after the target log.

Example 4: Diagnose an alert

Why was my cpu-high alert triggered over the last 24 hours? Run a diagnosis for me

The AI agent calls sls_diagnose_alert, which summarizes the lifecycle, severity, evaluation reason, and query evidence of the alert instance. The summary helps you locate the cause quickly.

Debug with MCP Inspector

To debug the tools and parameters of SLS MCP Server during development, use the official MCP Inspector to open a browser-based debugging interface. This command requires Node.js on your local machine, because Node.js provides the npx command. Replace sls-test-oauth with the name of your credential profile.

npx -y @modelcontextprotocol/inspector@latest -- uvx alibabacloud-sls-mcp-proxy@latest --profile sls-test-oauth

Supported tools

Tool	Category	Description
`sls_list_projects`	Resource discovery	Retrieves the SLS projects that the current caller can access. Supports filter conditions such as region, name, and resource group.
`sls_list_logstores`	Resource discovery	Retrieves the LogStores that store log data in a specified project. This tool excludes metricstores.
`sls_list_metricstores`	Resource discovery	Retrieves the metricstores that store metric data in a specified project.
`sls_get_logstore_index`	Log query and analysis	Retrieves the index configuration of a LogStore.
`sls_query_logs`	Log query and analysis	Queries Raw Logs or runs an SLS SQL analysis. Supports relative time ranges.
`sls_get_log_histogram`	Log query and analysis	Queries the total number of matched logs and their distribution over time within a specified time range.
`sls_get_context_logs`	Log query and analysis	Retrieves the context before and after a target log. The `pack_id` and `pack_meta` parameters take the `__pack_id__` and `__pack_meta__` values of the target log.
`sls_list_alerts`	Alert diagnostics	Lists a security summary of alert rules by page. Query statements and notification targets are not returned.
`sls_get_alert`	Alert diagnostics	Retrieves the schedule, trigger conditions, and diagnostic queries of a single alert rule. Sensitive notification configurations are masked.
`sls_list_alert_history`	Alert diagnostics	Queries the firing and resolved history of an alert rule, together with the query results that the alert engine saved at that time.
`sls_diagnose_alert`	Alert diagnostics	Summarizes the lifecycle, severity, evaluation reason, and query evidence of recent alert instances. Does not change the alert state.

Tool parameters

The following tables describe the input parameters of each tool. When you call a tool through an AI agent, you usually do not need to handle these parameters because the AI agent fills them in automatically. Use these tables for advanced usage and debugging.

sls_list_projects

Parameter	Type	Required	Description
`offset`	integer	No	The zero-based pagination offset. Default value: 0.
`size`	integer	No	The number of projects to return per page. The default value and the maximum value in SLS are both 500.
`region_id`	string	No	Filters by SLS region ID, for example, `cn-hangzhou`.
`project_name`	string	No	Filters by project name. This field is a search condition and is not validated against the exact resource naming rules.
`resource_group_id`	string	No	Filters by resource group ID.
`search_text`	string	No	The free-text search condition for projects.

sls_list_logstores

Parameter	Type	Required	Description
`project`	string	Yes	The name of the target SLS project.
`offset`	integer	No	The zero-based pagination offset. Default value: 0.
`size`	integer	No	The number of LogStores to return per page. The default value and the maximum value in SLS are both 500.

sls_list_metricstores

Parameter	Type	Required	Description
`project`	string	Yes	The name of the target SLS project.
`offset`	integer	No	The zero-based pagination offset. Default value: 0.
`size`	integer	No	The number of metricstores to return per page. The default value and the maximum value in SLS are both 500.

sls_get_logstore_index

Parameter	Type	Required	Description
`project`	string	Yes	The name of the target SLS project.
`logstore`	string	Yes	The name of the LogStore whose index configuration you want to read.

sls_query_logs

Parameter	Type	Required	Description
`project`	string	Yes	The name of the target SLS project.
`logstore`	string	Yes	The name of the LogStore that you want to query.
`query`	string	No	The SLS query statement or analytic statement. Default value: empty.
`topic`	string	No	The SLS topic filter condition.
`from`	string	Yes	The beginning of the query time range. The specified point in time is included, for example, `1786342175`. Supports Unix seconds or a relative time such as `now-1h`.
`to`	string	Yes	The end of the query time range. The specified point in time is excluded, for example, `1786342175`. Supports Unix seconds or a relative time such as `now`.
`lines`	integer	No	The maximum number of lines to return for a non-SQL query. The default value and the maximum value in SLS are both 100.
`offset`	integer	No	The zero-based result offset for a non-SQL query. Default value: 0.
`reverse`	boolean	No	Specifies whether to return the results of a non-SQL query in reverse chronological order. Default value: `false`.
`power_sql`	boolean	No	Specifies whether to use dedicated SQL compute resources. Default value: `false`.

sls_get_log_histogram

Parameter	Type	Required	Description
`project`	string	Yes	The name of the target SLS project.
`logstore`	string	Yes	The name of the LogStore that you want to query.
`from`	integer	Yes	The beginning of the query time range, in Unix seconds. The specified point in time is included.
`to`	integer	Yes	The end of the query time range, in Unix seconds. The specified point in time is excluded.
`topic`	string	No	The SLS topic filter condition.
`query`	string	No	The SLS query expression. SQL analysis is not supported.

sls_get_context_logs

Parameter	Type	Required	Description
`project`	string	Yes	The name of the target SLS project.
`logstore`	string	Yes	The name of the LogStore that contains the target log.
`pack_id`	string	Yes	The `__pack_id__` value from the previous `sls_query_logs` result.
`pack_meta`	string	Yes	The `__pack_meta__` value from the previous `sls_query_logs` result.
`back_lines`	integer	No	The number of log lines to return before the target log. Default value: 10. Maximum value: 100.
`forward_lines`	integer	No	The number of log lines to return after the target log. Default value: 10. Maximum value: 100.

sls_list_alerts

Parameter	Type	Required	Description
`project`	string	Yes	The name of the SLS project that contains the target alert rules.
`alert_name`	string	No	The alert rule name filter condition.
`dashboard`	string	No	The dashboard resource provider filter condition.
`offset`	integer	No	The zero-based pagination offset. Default value: 0.
`size`	integer	No	The number of alert rules to return per page. If the value is 0 or the parameter is omitted, the default value of the SLS API is used.

sls_get_alert

Parameter	Type	Required	Description
`project`	string	Yes	The name of the SLS project that contains the target alert rule.
`alert_name`	string	Yes	The exact name of the alert rule that you want to retrieve.

sls_list_alert_history

Parameter	Type	Required	Description
`project`	string	Yes	The name of the SLS project that contains the `internal-alert-history` LogStore.
`alert_name`	string	No	Filters by the exact name of the alert rule.
`alert_id`	string	No	Filters by the exact ID of the alert instance.
`alert_status`	string	No	Filters by the lifecycle state of the alert, for example, `firing` or `resolved`.
`from`	string	Yes	The beginning of the history query time range. The specified point in time is included. Supports Unix seconds or a relative time such as `now-24h`.
`to`	string	Yes	The end of the history query time range. The specified point in time is excluded. Supports Unix seconds or a relative time such as `now`.
`lines`	integer	No	The maximum number of history events. Default value: 20. Maximum value: 100.
`offset`	integer	No	The zero-based history result offset. Default value: 0.

sls_diagnose_alert

Parameter	Type	Required	Description
`project`	string	Yes	The name of the SLS project that contains the alert rule and the `internal-alert-history` LogStore.
`alert_name`	string	Yes	The exact name of the alert rule that you want to diagnose.
`alert_id`	string	No	The ID of the alert instance. If you omit this parameter, the latest matching instance within the diagnosis time range is diagnosed.
`from`	string	Yes	The beginning of the diagnosis time range. The specified point in time is included. Supports Unix seconds or a relative time such as `now-24h`.
`to`	string	Yes	The end of the diagnosis time range. The specified point in time is excluded. Supports Unix seconds or a relative time such as `now`.
`max_events`	integer	No	The number of latest history events to return as diagnosis evidence. Default value: 20. Maximum value: 100.

FAQ

Do I need to configure an AccessKey pair to use SLS MCP Server?

No. SLS MCP Server supports OAuth sign-in: you sign in through a browser to complete authentication, and the credentials are stored in an Alibaba Cloud CLI profile. You never create or paste an AccessKey pair.

Does the RAM administrator authorization need to be repeated?

No. This is a one-time setup. After a RAM administrator installs the official-cli application and assigns RAM users or roles, those users can sign in with OAuth directly without repeating the steps.

How do I manage multiple accounts or multiple environments?

Use the -p parameter to create multiple profiles, for example, aliyun configure --mode OAuth -p sls-test-oauth. Then specify the corresponding profile name with the --profile parameter when you add SLS MCP Server to your client. You can also add a separate MCP server for each profile.

Which region do I enter when I configure credentials?

Enter cn-hangzhou when the CLI prompts you for a region, as described in Step 2. The value does not limit the projects that you can reach, because SLS MCP Server matches the corresponding region automatically when you access a project. To view the resources in only one region, filter by the region_id parameter when you list projects.

What do I do if the `uvx` command is not found?

The uvx command is provided by the uv tool, which is a prerequisite for SLS MCP Server. Install uv first. For installation instructions, see the uv documentation. After the installation is complete, open a new terminal and try again.