Content
# aliyun-sls-mcp-server
`aliyun-sls-mcp-server` is a TypeScript + Express-based MCP service that allows AI Agents to query Alibaba Cloud's Simple Log Service (SLS) through MCP.
It is suitable for scenarios such as:
- Online fault diagnosis
- Daily research and development log queries
- Querying error/warn/info logs for certain services
- Querying link logs through traceId/TID
- Viewing log volume distribution and error trends for a service over a period
The underlying data source is Alibaba Cloud SLS, and the current service only provides read-only queries, without writing logs or modifying SLS configurations.
## Effect Display
- Query error logs for the last 15 minutes
<img width="3024" height="1740" alt="image" src="https://github.com/user-attachments/assets/c667fe0a-eaca-47d0-a133-59deb01b7c2d" />
- Query error logs for a specific service
<img width="3024" height="1740" alt="image" src="https://github.com/user-attachments/assets/e8a94492-7706-4979-a835-e8af01b1d48c" />
<img width="2056" height="964" alt="image" src="https://github.com/user-attachments/assets/0fd64a9b-9f05-44ef-bb79-933d878b7e7f" />
- Query error logs through link ID and analyze the issue
<img width="3024" height="1740" alt="image" src="https://github.com/user-attachments/assets/8c1d9024-be5e-4430-bdde-214dbd5e9f6c" />
<img width="3024" height="1740" alt="image" src="https://github.com/user-attachments/assets/35e6a215-d7fe-4f3e-b7b6-6be10f06b398" />
- View log volume distribution and error trends for a service over a period
<img width="1788" height="1272" alt="image" src="https://github.com/user-attachments/assets/61270e82-42c5-47be-8730-b2977ce6e041" />
## Functional Characteristics
- Query accessible SLS Projects for the current account
- Query Logstores under a specific Project
- Query log details, using `GetLogsV2` under the hood
- Query log volume distribution, using `GetHistograms` under the hood
- Support environment mapping for Project + Logstore, e.g., `test`, `staging`, `prod`
- Support querying by service name/container name, defaulting to `_container_name_`
- Support `info`, `warn`, `error` log levels
- Support traceId/TID queries, defaulting to 7 days, configurable
- Support pagination, returning `nextPage` for Agent to continue flipping pages
- Support limiting returned fields to reduce model context occupation
- Provide Streamable HTTP MCP service
- Provide HTTP debugging interface for verification with browser, Postman, or curl
## Not Suitable for
The current project is positioned as "log query" and "auxiliary troubleshooting". It is not recommended for SLS management operations.
The current service does not support and does not plan to open the following high-risk capabilities by default:
- Writing logs
- Creating or deleting Projects/Logstores
- Creating, modifying, or deleting indexes
- Modifying alerts, dashboards, and delivery tasks
- Managing machine groups, Logtail configurations
- Executing unrestricted large-scale SQL analysis
## Official Documentation
This project is built based on Alibaba Cloud SLS OpenAPI. It is recommended to read the official documentation to understand SLS query syntax, permissions, and interface restrictions.
- [Alibaba Cloud Simple Log Service (SLS) Documentation](https://help.aliyun.com/zh/sls/)
- [SLS OpenAPI Overview](https://help.aliyun.com/zh/sls/developer-reference/api-sls-2020-12-30-overview)
- [GetLogsV2 Query Logs](https://help.aliyun.com/zh/sls/developer-reference/api-sls-2020-12-30-getlogsv2)
- [GetHistograms Query Log Distribution](https://help.aliyun.com/zh/sls/developer-reference/api-sls-2020-12-30-gethistograms)
If the specific API link changes, please refer to the SLS OpenAPI overview and Alibaba Cloud console documentation entry.
## Obtaining Alibaba Cloud Access Credentials
This service accesses SLS through Alibaba Cloud OpenAPI and requires configuring AccessKey.
It is recommended to create a dedicated RAM user and grant only SLS read-only query permissions. Do not use the main account AccessKey.
Reference documentation:
- [Create AccessKey](https://help.aliyun.com/zh/ram/user-guide/create-an-accesskey-pair)
- [RAM User Overview](https://help.aliyun.com/zh/ram/user-guide/users)
- [Grant Permissions to RAM Users](https://help.aliyun.com/zh/ram/user-guide/grant-permissions-to-the-ram-user)
The current service requires at least the following SLS query capabilities:
- Query Projects
- Query Logstores
- Query log details, `GetLogsV2`
- Query log distribution, `GetHistograms`
RAM permission policy action names should be based on Alibaba Cloud official permission documentation and console generation. In a production environment, use the minimum permissions and do not grant write, delete, index modification, or alert modification permissions.
## Quick Start
```bash
git clone https://github.com/LilMosey/aliyun-sls-mcp-server.git
cd aliyun-sls-mcp-server
npm install
cp .env.example .env.local
```
Edit `.env.local` and fill in your Alibaba Cloud configuration:
```bash
PORT=3000
SERVICE_NAME=aliyun-sls-mcp-server
ALIYUN_LOG_ACCESS_KEY_ID="YourAccessKeyId"
ALIYUN_LOG_ACCESS_KEY_SECRET="YourAccessKeySecret"
ALIYUN_LOG_REGION=cn-hangzhou
ALIYUN_LOG_DEFAULT_ENVIRONMENT=test
ALIYUN_LOG_ENVIRONMENTS={"test":{"projectName":"k8s-dev","logstoreName":"test"},"staging":{"projectName":"k8s-dev","logstoreName":"staging"}}
```
Start the development service:
```bash
npm run dev
```
Health check:
```bash
curl http://localhost:3000/health
```
Expected return:
```json
{
"status": "ok",
"service": "aliyun-sls-mcp-server"
}
```
## Environment Variables
`.env.example` is the template submitted to Git and should not contain real keys. `.env.local` is used to save the local configuration and is ignored by `.gitignore`.
| Variable | Required | Default Value | Description |
|---|---:|---|---|
| `PORT` | No | `3000` | HTTP service port |
| `SERVICE_NAME` | No | `aliyun-sls-mcp-server` | Health check returned service name |
| `ALIYUN_LOG_ACCESS_KEY_ID` | Yes | None | Alibaba Cloud AccessKey ID |
| `ALIYUN_LOG_ACCESS_KEY_SECRET` | Yes | None | Alibaba Cloud AccessKey Secret |
| `ALIYUN_LOG_REGION` | Yes | None | SLS region, e.g., `cn-hangzhou` |
| `ALIYUN_LOG_ENDPOINT` | No | `${ALIYUN_LOG_REGION}.log.aliyuncs.com` | Custom SLS endpoint |
| `ALIYUN_LOG_ENVIRONMENTS` | No | Built-in `test` example | Environment to Project/Logstore mapping |
| `ALIYUN_LOG_DEFAULT_ENVIRONMENT` | No | `test` | Default query environment |
| `ALIYUN_LOG_DEFAULT_QUERY_MINUTES` | No | `15` | Ordinary query default time window |
| `ALIYUN_LOG_MAX_QUERY_MINUTES` | No | `30` | Ordinary non-empty query maximum time window |
| `ALIYUN_LOG_EMPTY_QUERY_MAX_MINUTES` | No | `5` | Empty query maximum time window |
| `ALIYUN_LOG_TRACE_DEFAULT_QUERY_MINUTES` | No | `10080` | traceId/TID default query window, default 7 days |
| `ALIYUN_LOG_TRACE_MAX_QUERY_MINUTES` | No | `10080` | traceId/TID maximum query window |
| `ALIYUN_LOG_TRACE_MIN_LENGTH` | No | `16` | traceId/TID minimum length |
| `ALIYUN_LOG_DEFAULT_PAGE_SIZE` | No | `50` | Log details default page size |
| `ALIYUN_LOG_MAX_PAGE_SIZE` | No | `100` | Log details maximum page size |
| `ALIYUN_LOG_RETURN_FIELDS` | No | Return all fields | Limit each log returned raw fields |
`ALIYUN_LOG_ENVIRONMENTS` example:
```bash
ALIYUN_LOG_ENVIRONMENTS={"test":{"projectName":"k8s-dev","logstoreName":"test"},"staging":{"projectName":"k8s-dev","logstoreName":"staging"}}
```
MCP tool descriptions will read environment names configured here and prompt the Agent with available environments and default environments. After modifying `ALIYUN_LOG_ENVIRONMENTS`, restart the service and let the MCP client reconnect to get the new tool descriptions.
`ALIYUN_LOG_RETURN_FIELDS` example:
```bash
ALIYUN_LOG_RETURN_FIELDS=time,level,_container_name_,_pod_name_,_namespace_,content
```
Field names must match the raw fields returned by Alibaba Cloud. For example, the service name field is usually `_container_name_`, not `containerName`.
## MCP Service
The current Streamable HTTP MCP service is provided:
```text
POST /mcp
GET /mcp
DELETE /mcp
```
MCP uses stateful Streamable HTTP:
- Initialization request returns `mcp-session-id`
- Subsequent `POST /mcp` needs to bring the same `mcp-session-id`
- `GET /mcp` uses the same `mcp-session-id` to establish an SSE long connection for receiving service notifications
- `DELETE /mcp` uses the same `mcp-session-id` to terminate the session
MCP client configuration example:
```json
{
"mcpServers": {
"aliyun-sls-mcp-server": {
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
}
}
```
If your MCP client uses a simpler server list format, you can rewrite it as follows:
```json
{
"name": "aliyun-sls-mcp-server",
"type": "streamable-http",
"url": "http://localhost:3000/mcp"
}
```
Different MCP clients may have different configuration fields, e.g., some use `streamable-http`, others use `http` or `streamableHttp`. Please refer to the corresponding client documentation. The core connection address is:
```text
http://localhost:3000/mcp
```
## MCP Tools
| Tool Name | Function |
|---|---|
| `aliyun_log_list_projects` | Query accessible SLS Projects for the current account in a specified region |
| `aliyun_log_list_logstores` | Query Logstores under a specific Project |
| `aliyun_log_query_logs` | Query log details, service logs, error logs, and traceId/TID link logs |
| `aliyun_log_get_histograms` | Query log volume distribution, error trends, and fault start time clues |
### `aliyun_log_query_logs`
Common parameters:
```json
{
"environment": "staging",
"containerNames": ["user-service"],
"level": "error",
"minutes": 30,
"pageNumber": 1,
"pageSize": 50
}
```
Description:
- If `environment` is not passed, use `ALIYUN_LOG_DEFAULT_ENVIRONMENT`
- `containerNames` is any service name/container name, and the service will拼成 `_container_name_` for querying
- `level` only supports `info`, `warn`, `error`
- `traceId` will拼成 `content: "traceId"`
- When users say "recent N minutes/hours", it's suitable to pass `minutes`
- When users say "today 14:00 to 15:00" with a clear time range, the Agent should convert it to Unix seconds `from` and `to` based on `Asia/Shanghai`
- `from/to` and `minutes` cannot be passed at the same time
- When returning `nextPage`, the next page should directly reuse the parameters in `nextPage` to avoid recalculating the time window
### `aliyun_log_get_histograms`
Common parameters:
```json
{
"environment": "staging",
"containerNames": ["user-service"],
"level": "error",
"minutes": 120
}
```
This tool only returns the log volume for each time period and does not return log details. It's suitable for first determining if there's an error spike and then using `aliyun_log_query_logs` to query specific logs.
## Prompt Examples
Query error logs for the last 30 minutes for a specific service:
```text
Help me query error logs for the user-service in the staging environment for the last 30 minutes.
```
View error trends:
```text
Help me view error log distribution for the user-service in the staging environment over the last 2 hours to determine if there's a spike.
```
Query logs for a fixed time range:
```text
Help me query error logs for the user-service in the staging environment from 14:00 to 15:00 today.
```
Query traceId/TID link:
```text
Help me query link logs for this traceId over the last 7 days: b03a2133ebe048ccae56cb40125bb53d.574.17827209165150053
```
View trends and then query peak periods:
```text
Help me view error log distribution for the user-service in the staging environment over the last 2 hours. If there's a significant spike, query the error log details for the peak period.
```
## HTTP Debugging Interface
The HTTP interface is mainly used for local debugging and verifying Alibaba Cloud configurations.
Query Projects:
```bash
curl "http://localhost:3000/aliyun-log/projects"
```
Query Logstores:
```bash
curl "http://localhost:3000/aliyun-log/projects/k8s-dev/logstores"
```
Query logs by environment:
```bash
curl --get "http://localhost:3000/aliyun-log/logs" \
--data-urlencode "environment=staging" \
--data-urlencode "containerNames=user-service" \
--data-urlencode "level=error" \
--data-urlencode "minutes=30"
```
Query traceId/TID:
```bash
curl --get "http://localhost:3000/aliyun-log/logs" \
--data-urlencode "environment=staging" \
--data-urlencode "traceId=b03a2133ebe048ccae56cb40125bb53d.574.17827209165150053"
```
Query log distribution:
```bash
curl --get "http://localhost:3000/aliyun-log/histograms" \
--data-urlencode "environment=staging" \
--data-urlencode "containerNames=user-service" \
--data-urlencode "level=error" \
--data-urlencode "minutes=120"
```
Directly specify Project + Logstore:
```bash
curl --get "http://localhost:3000/aliyun-log/projects/k8s-dev/logstores/staging/logs" \
--data-urlencode "query=level: error" \
--data-urlencode "from=1719390000" \
--data-urlencode "to=1719390900"
```
## Security Suggestions
- Do not submit `.env.local`
- Do not use the main account AccessKey
- Create a dedicated RAM user for this service
- Grant only SLS read-only query permissions
- Deploy in a private or controlled network in a production environment
- Add authentication in the reverse proxy layer in a production environment
- Logs may contain sensitive information like phone numbers, emails, user IDs, request parameters, and business data. Please be cautious when exposing them to external Agents.
- If you need to control returned fields, configure `ALIYUN_LOG_RETURN_FIELDS` to reduce sensitive fields and context occupation.
Development Commandsbash
npm run dev typecheck
build
npm start- `npm`: Starts the development `tsx watch`
- `npm run typecheck`: Performs checking only,ting files
- ` build`: Compilesdist`
- `npm start`: Runs the compiled `dist/src`
## Projecttext
src/
.ts # Process entry port
# Express application assembly
config/env.ts # Basic reading
routes/
.ts # Health check
mcp.ts # Stream MCP route
m.ts # MCP Server and
mcp-tools/
iyun-log-tool.ts # MCP tool name, description, and parameter schema
cp-services/
aliyun-log/
client.ts yun SLS
config.ts # SLS configuration reading
.ts # ListProjectstores.ts #Stores
logs.ts # GetLogsV2
# GetHistograms
routes.ts # HTTP debugging interface
```
## Roadmap
- Docker image and deployment example
- RAM minimum permission Policy example
- More MCP client access examples
- Optional authentication middleware
- More complete log desensitization configuration
- Controlled SQL aggregation capabilities, such as service-based error Top N statistics
## License
MIT
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available