Aliyun Sls

aliyun-sls-mcp-server 是一个基于 TypeScript + Express 的 MCP 服务，用于让 AI Agent 通过 MCP 查询阿里云日志服务 SLS。

它适合这些场景：

• 线上故障排查
• 日常研发查日志
• 查询某些服务的 error/warn/info 日志
• 通过 traceId/TID 查询链路日志
• 查看某个服务在一段时间内的日志数量分布和报错趋势

底层数据源是阿里云 SLS，当前服务只做只读查询，不写入日志，不修改 SLS 配置。

效果展示

• 查询最近15分钟错误日志

• 查询某个服务的错误日志

• 通过链路id查询错误日志，并分析问题

• 查看某个服务在一段时间内的日志数量分布和报错趋势

功能特性

• 查询当前账号可访问的 SLS Project
• 查询某个 Project 下的 Logstore
• 查询日志明细，底层使用 GetLogsV2
• 查询日志数量分布，底层使用 GetHistograms
• 支持按环境映射 Project + Logstore，例如 test、staging、prod
• 支持按服务名/容器名查询，字段默认使用 _container_name_
• 支持 info、warn、error 日志级别
• 支持 traceId/TID 查询，默认可查最近 7 天，可配置
• 支持分页，返回 nextPage 方便 Agent 继续翻页
• 支持限制返回字段，减少模型上下文占用
• 提供 Streamable HTTP MCP 服务
• 提供 HTTP 调试接口，方便用浏览器、Postman 或 curl 验证

不适合做什么

当前项目定位是“查日志”和“辅助排障”，不建议用它做 SLS 管理操作。

当前不支持，也不计划默认开放这些高风险能力：

• 写入日志
• 创建或删除 Project/Logstore
• 创建、修改或删除索引
• 修改告警、仪表盘、投递任务
• 管理机器组、Logtail 配置
• 执行无限制的大范围 SQL 分析

官方文档

本项目基于阿里云 SLS OpenAPI 构建，建议先阅读官方文档了解 SLS 的查询语法、权限和接口限制。

• 阿里云日志服务 SLS 文档
• SLS OpenAPI 概览
• GetLogsV2 查询日志
• GetHistograms 查询日志分布

如果具体 API 链接发生变化，以 SLS OpenAPI 概览和阿里云控制台文档入口为准。

获取阿里云访问凭证

本服务通过阿里云 OpenAPI 访问 SLS，需要配置 AccessKey。

建议创建一个专用 RAM 用户，并只授予 SLS 只读查询权限。不要使用阿里云主账号 AccessKey。

参考文档：

• 创建 AccessKey
• RAM 用户概览
• 为 RAM 用户授权

当前服务至少需要这些 SLS 查询能力：

• 查询 Project
• 查询 Logstore
• 查询日志明细，GetLogsV2
• 查询日志分布，GetHistograms

RAM 权限策略里的 Action 名称建议以阿里云官方权限文档和控制台生成为准。生产环境请使用最小权限，不要授予写入、删除、索引修改、告警修改等权限。

快速开始

git clone https://github.com/LilMosey/aliyun-sls-mcp-server.git
cd aliyun-sls-mcp-server
npm install
cp .env.example .env.local

编辑 .env.local，填入你的阿里云配置：

PORT=3000
SERVICE_NAME=aliyun-sls-mcp-server

ALIYUN_LOG_ACCESS_KEY_ID="你的AccessKeyId"
ALIYUN_LOG_ACCESS_KEY_SECRET="你的AccessKeySecret"
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"}}

启动开发服务：

npm run dev

健康检查：

curl http://localhost:3000/health

预期返回：

{
  "status": "ok",
  "service": "aliyun-sls-mcp-server"
}

环境变量

.env.example 是提交到 Git 的模板，不应该放真实密钥。.env.local 用于保存本机真实配置，已经被 .gitignore 忽略。

变量	必填	默认值	说明
PORT	否	3000	HTTP 服务端口
SERVICE_NAME	否	aliyun-sls-mcp-server	健康检查返回的服务名
ALIYUN_LOG_ACCESS_KEY_ID	是	无	阿里云 AccessKey ID
ALIYUN_LOG_ACCESS_KEY_SECRET	是	无	阿里云 AccessKey Secret
ALIYUN_LOG_REGION	是	无	SLS 区域，例如 cn-hangzhou
ALIYUN_LOG_ENDPOINT	否	${ALIYUN_LOG_REGION}.log.aliyuncs.com	自定义 SLS endpoint
ALIYUN_LOG_ENVIRONMENTS	否	内置 test 示例	环境到 Project/Logstore 的映射
ALIYUN_LOG_DEFAULT_ENVIRONMENT	否	test	默认查询环境
ALIYUN_LOG_DEFAULT_QUERY_MINUTES	否	15	普通查询默认时间窗口
ALIYUN_LOG_MAX_QUERY_MINUTES	否	30	普通非空查询最大时间窗口
ALIYUN_LOG_EMPTY_QUERY_MAX_MINUTES	否	5	空查询最大时间窗口
ALIYUN_LOG_TRACE_DEFAULT_QUERY_MINUTES	否	10080	traceId/TID 默认查询窗口，默认 7 天
ALIYUN_LOG_TRACE_MAX_QUERY_MINUTES	否	10080	traceId/TID 最大查询窗口
ALIYUN_LOG_TRACE_MIN_LENGTH	否	16	traceId/TID 最小长度
ALIYUN_LOG_DEFAULT_PAGE_SIZE	否	50	日志明细默认每页条数
ALIYUN_LOG_MAX_PAGE_SIZE	否	100	日志明细最大每页条数
ALIYUN_LOG_RETURN_FIELDS	否	返回全部字段	限制每条日志返回的原始字段

ALIYUN_LOG_ENVIRONMENTS 示例：

ALIYUN_LOG_ENVIRONMENTS={"test":{"projectName":"k8s-dev","logstoreName":"test"},"staging":{"projectName":"k8s-dev","logstoreName":"staging"}}

MCP 工具描述会在服务启动时读取这里配置的环境名，并提示 Agent 当前可用环境和默认环境。修改 ALIYUN_LOG_ENVIRONMENTS 后，需要重启服务并让 MCP 客户端重新连接，客户端才能拿到新的工具描述。

ALIYUN_LOG_RETURN_FIELDS 示例：

ALIYUN_LOG_RETURN_FIELDS=time,level,_container_name_,_pod_name_,_namespace_,content

字段名要和阿里云返回的原始字段保持一致。例如服务名字段通常是 _container_name_，不是 containerName。

MCP 服务

当前提供 Streamable HTTP MCP 服务：

POST /mcp
GET /mcp
DELETE /mcp

MCP 使用 stateful Streamable HTTP：

• 初始化请求会返回 mcp-session-id
• 后续 POST /mcp 需要带同一个 mcp-session-id
• GET /mcp 使用同一个 mcp-session-id 建立 SSE 长连接，用于接收服务端通知
• DELETE /mcp 使用同一个 mcp-session-id 终止会话

MCP 客户端配置示例：

{
  "mcpServers": {
    "aliyun-sls-mcp-server": {
      "type": "streamable-http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

如果你的 MCP 客户端使用更简单的 server 列表格式，可以按下面这种结构改写：

{
  "name": "aliyun-sls-mcp-server",
  "type": "streamable-http",
  "url": "http://localhost:3000/mcp"
}

不同 MCP 客户端的配置字段可能不同，例如有的客户端使用 streamable-http，有的客户端使用 http 或 streamableHttp。请以对应客户端文档为准，核心连接地址是：

http://localhost:3000/mcp

MCP 工具

工具名	作用
aliyun_log_list_projects	查询当前账号在指定区域下可访问的 SLS Project
aliyun_log_list_logstores	查询某个 Project 下的 Logstore
aliyun_log_query_logs	查询日志明细、服务日志、报错日志、traceId/TID 链路日志
aliyun_log_get_histograms	查询日志数量分布、错误趋势、故障开始时间线索

aliyun_log_query_logs

常用参数：

{
  "environment": "staging",
  "containerNames": ["user-service"],
  "level": "error",
  "minutes": 30,
  "pageNumber": 1,
  "pageSize": 50
}

说明：

• environment 不传时使用 ALIYUN_LOG_DEFAULT_ENVIRONMENT
• containerNames 是任意服务名/容器名，服务端会拼成 _container_name_ 查询
• level 只支持 info、warn、error
• traceId 会拼成 content: "traceId"
• 用户说“最近 N 分钟/小时”时，适合传 minutes
• 用户说“今天 14:00 到 15:00”这种明确时间段时，Agent 应按 Asia/Shanghai 换算成 Unix 秒级 from 和 to
• from/to 和 minutes 不能同时传
• 返回 nextPage 时，下一次翻页应直接复用 nextPage 里的参数，避免重新计算时间窗口

aliyun_log_get_histograms

常用参数：

{
  "environment": "staging",
  "containerNames": ["user-service"],
  "level": "error",
  "minutes": 120
}

这个工具只返回每个时间段的日志数量，不返回日志明细。适合先判断是否有错误突增，再用 aliyun_log_query_logs 查询具体日志。

Prompt 示例

查询最近 30 分钟某个服务的错误日志：

帮我查询 staging 环境 user-service 最近 30 分钟的 error 日志

查看错误趋势：

帮我看 staging 环境 user-service 最近 2 小时 error 日志分布，判断有没有突增

查询固定时间段日志：

帮我查 staging 环境 user-service 今天 14:00 到 15:00 的错误日志

查询 traceId/TID 链路：

帮我查询这个 traceId 最近 7 天的链路日志：b03a2133ebe048ccae56cb40125bb53d.574.17827209165150053

先看趋势，再查峰值时间段：

帮我看 staging 环境 user-service 最近 2 小时 error 日志分布，如果有明显峰值，再查询峰值时间段的错误日志明细

HTTP 调试接口

HTTP 接口主要用于本地调试和验证阿里云配置是否正确。

查询 Project：

curl "http://localhost:3000/aliyun-log/projects"

查询 Logstore：

curl "http://localhost:3000/aliyun-log/projects/k8s-dev/logstores"

按环境查询日志：

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"

查询 traceId/TID：

curl --get "http://localhost:3000/aliyun-log/logs" \
  --data-urlencode "environment=staging" \
  --data-urlencode "traceId=b03a2133ebe048ccae56cb40125bb53d.574.17827209165150053"

查询日志分布：

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"

直接指定 Project + Logstore：

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"

安全建议

• 不要提交 .env.local
• 不要使用阿里云主账号 AccessKey
• 建议为本服务创建专用 RAM 用户
• 建议只授予 SLS 只读查询权限
• 生产环境建议部署在内网或受控网络中
• 生产环境建议在反向代理层增加鉴权
• 日志可能包含手机号、邮箱、用户 ID、请求参数、业务数据等敏感信息，请谨慎暴露给外部 Agent
• 如果需要控制返回字段，请配置 ALIYUN_LOG_RETURN_FIELDS，减少敏感字段和上下文占用

开发命令

npm run dev
npm run typecheck
npm run build
npm start

说明：

• npm run dev：开发模式启动，使用 tsx watch
• npm run typecheck：只做 TypeScript 类型检查，不输出文件
• npm run build：编译到 dist
• npm start：运行编译后的 dist/src/server.js

项目结构

src/
  server.ts                         # 进程入口，监听端口
  app.ts                            # Express 应用组装
  config/env.ts                     # 基础环境变量读取
  routes/
    health.ts                       # 健康检查
    mcp.ts                          # Streamable HTTP MCP 路由
  mcp-server.ts                     # MCP Server 和工具注册
  mcp-tools/
    aliyun-log-tool-definitions.ts  # MCP 工具名、描述、入参 schema
  mcp-services/
    aliyun-log/
      client.ts                     # 阿里云 SLS SDK client
      config.ts                     # SLS 配置读取
      projects.ts                   # ListProject
      logstores.ts                  # ListLogStores
      logs.ts                       # GetLogsV2
      histograms.ts                 # GetHistograms
      routes.ts                     # HTTP 调试接口

Roadmap

• Docker 镜像和部署示例
• RAM 最小权限 Policy 示例
• 更多 MCP 客户端接入示例
• 可选鉴权中间件
• 更完整的日志脱敏配置
• 受控 SQL 聚合能力，例如按服务统计 error Top N

License

MIT