Skip to main content
Glama
LilMosey

MCP-SERVER

by LilMosey
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

aliyun-sls-mcp-server

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

它适合这些场景：

  • 线上故障排查

  • 日常研发查日志

  • 查询某些服务的 error/warn/info 日志

  • 通过 traceId/TID 查询链路日志

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

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

效果展示

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

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

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

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

Related MCP server: AWS AppRunner MCP Server

功能特性

  • 查询当前账号可访问的 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 的查询语法、权限和接口限制。

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

获取阿里云访问凭证

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

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

参考文档：

当前服务至少需要这些 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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Angular Bootstrap MCP Server

    palsuman
    A
    license
    Not graded
    quality
    D
    maintenance
    A TypeScript-based MCP server that provides backend API handling and facilitates communication between microservices. Features an organized structure with controllers, routes, and models for easy extensibility and maintenance.
    221 npm
    1
    MIT

  • MCP TypeScript Template

    mintedmaterial
    A
    license
    Not graded
    quality
    D
    maintenance
    A production-grade TypeScript template for building Model Context Protocol (MCP) servers with declarative tools/resources, authentication, storage abstraction, and support for both local and edge deployment. Provides example echo tools and resources to demonstrate MCP server development patterns.
    41 npm
    Apache 2.0

  • MCP Server Template

    cameronsjo
    A
    license
    A
    quality
    Not graded
    maintenance
    A production-ready TypeScript template for building MCP servers with dual transport support (stdio/HTTP), OAuth 2.1 foundations, SQLite caching, observability, and security features including PII sanitization and rate limiting.
    4
    4 npm
    -