aliyun-sls-mcp-py 0.1.0

MCP Server for Alibaba Cloud SLS (Log Service) - Pure Python

Aliyun SLS MCP Server (Pure Python)

阿里云 SLS (日志服务) MCP Server - 纯 Python 实现

特点

• 纯 Python: 无需 Node.js/npm
• 零安装: 通过 uvx 或 pipx 直接运行
• 轻量级: 仅依赖 mcp 和 aliyun-log-python-sdk
• FastMCP: 使用官方 Python SDK 的高级 API

安装与使用

方式一: uvx (推荐)

# 直接运行 (自动安装依赖)
export SLS_ENDPOINT=cn-hangzhou.log.aliyuncs.com
export SLS_ACCESS_KEY_ID=your-access-key-id
export SLS_ACCESS_KEY_SECRET=your-access-key-secret
export SLS_PROJECT=your-project

uvx aliyun-sls-mcp-py

方式二: pipx

pipx run aliyun-sls-mcp-py

方式三: pip 安装

pip install aliyun-sls-mcp-py

# 运行
SLS_ENDPOINT=xxx SLS_ACCESS_KEY_ID=xxx SLS_ACCESS_KEY_SECRET=xxx SLS_PROJECT=xxx \
    aliyun-sls-mcp-py

方式四: Claude Desktop 配置

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aliyun-sls": {
      "command": "uvx",
      "args": ["aliyun-sls-mcp-py"],
      "env": {
        "SLS_ENDPOINT": "cn-hangzhou.log.aliyuncs.com",
        "SLS_ACCESS_KEY_ID": "your-access-key-id",
        "SLS_ACCESS_KEY_SECRET": "your-access-key-secret",
        "SLS_PROJECT": "your-project",
        "SLS_LOGSTORE": "your-default-logstore"
      }
    }
  }
}

方式五: Cursor IDE 配置

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "aliyun-sls": {
      "command": "uvx",
      "args": ["aliyun-sls-mcp-py"],
      "env": {
        "SLS_ENDPOINT": "cn-hangzhou.log.aliyuncs.com",
        "SLS_ACCESS_KEY_ID": "your-access-key-id",
        "SLS_ACCESS_KEY_SECRET": "your-access-key-secret",
        "SLS_PROJECT": "your-project"
      }
    }
  }
}

环境变量

变量名	必填	说明
SLS_ENDPOINT	是	SLS 服务端点，如 cn-hangzhou.log.aliyuncs.com
SLS_ACCESS_KEY_ID	是	阿里云 AccessKey ID
SLS_ACCESS_KEY_SECRET	是	阿里云 AccessKey Secret
SLS_PROJECT	是	SLS 项目名称
SLS_LOGSTORE	否	默认日志库名称

提供的工具

1. list_logstores

列出当前项目下所有的日志库

无需参数

2. query_logs

查询 SLS 日志（支持分页）

参数	类型	必填	说明
query	string	是	SLS 查询语句
logstore	string	否	日志库名称
from_time	string	否	开始时间 (默认 -1h)
to_time	string	否	结束时间 (默认 now)
limit	int	否	每页条数 (默认 100, 最大 500)
offset	int	否	偏移量 (默认 0)

3. search_keyword

搜索包含关键字的日志

参数	类型	必填	说明
keyword	string	是	搜索关键字
logstore	string	否	日志库名称
from_time	string	否	开始时间 (默认 -24h)
to_time	string	否	结束时间 (默认 now)
limit	int	否	每页条数 (默认 20)
offset	int	否	偏移量 (默认 0)

4. analyze_errors

分析错误日志

参数	类型	必填	说明
logstore	string	否	日志库名称
from_time	string	否	开始时间 (默认 -24h)
to_time	string	否	结束时间 (默认 now)
top_n	int	否	返回前N个高频错误 (默认 10)

提供的资源

• sls://config - 当前 SLS 配置信息
• sls://help - SLS 查询语法帮助
• sls://logstores - 所有日志库列表

提供的提示词

• analyze_errors_prompt - 错误日志分析提示词
• search_logs_prompt - 日志搜索提示词

时间格式支持

支持多种时间格式:

格式	示例	说明
相对时间	-1h, -30m, -7d	1小时前、30分钟前、7天前
当前时间	now	当前时间戳
ISO 格式	2024-01-01T00:00:00	ISO 8601 格式
Unix 时间戳	1704067200	秒或毫秒时间戳

开发

# 克隆项目
git clone https://github.com/dongmaowei/aliyun-sls-mcp-py.git
cd aliyun-sls-mcp-py

# 使用 uv 创建虚拟环境
uv venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 安装依赖
uv sync

# 开发模式运行
uv run mcp dev src/aliyun_sls_mcp_py/server.py

# 直接运行
uv run python -m aliyun_sls_mcp_py.server

测试

# 运行测试
uv run pytest

# 测试 MCP 服务器
uv run mcp dev src/aliyun_sls_mcp_py/server.py

发布到 PyPI

# 安装构建工具
uv pip install build twine

# 构建
python -m build

# 上传到 PyPI
twine upload dist/*

# 或使用 uv
uv publish

三种方案对比

特性	Python + npm 混合	纯 Node.js	纯 Python
依赖	Python + uv + npm	Node.js	Python + uv
启动	npx -y @scope/pkg	npx -y @scope/pkg	uvx pkg
包大小	较大	小	中
开发效率	高	中	高
SDK 成熟度	FastMCP	底层 API	FastMCP
适用场景	npm 生态用户	前端团队	Python 生态用户

License

MIT