# Elasticsearch 日志查询 MCP

这是一个只读的 Elasticsearch MCP 服务，适合让 Codex、Claude Desktop 等 MCP
客户端辅助排查日志。

## 功能

- `check_connection`：检查 ES 连接和版本
- `list_indices`：发现日志索引
- `get_index_fields`：查看字段及类型
- `search_logs`：按关键词、时间范围和精确字段过滤日志
- `get_log_context`：查看某条异常时间点前后的日志
- `aggregate_logs`：按日志级别、服务、主机等字段统计，并可生成时间趋势

所有工具均为只读操作。单次最多返回 200 条日志。

## 安装与启动

```powershell
python -m pip install -r requirements.txt
python es_mcp_server.py
```

默认连接信息与原 `testes.py` 一致。生产使用建议通过环境变量覆盖：

```powershell
$env:ES_URL = "http://127.0.0.1:9200"
$env:ES_USERNAME = "elastic"
$env:ES_PASSWORD = "your-password"
python es_mcp_server.py
```

如果 Elasticsearch 有多个节点，可以使用 `ES_URLS`，地址用逗号分隔；不写协议时会自动按 `http://` 处理：

```powershell
$env:ES_URLS = "10.128.100.97:9200,10.128.100.98:9200,10.128.100.99:9200"
python es_mcp_server.py
```

## MCP 客户端配置

将下面配置加入客户端的 MCP servers 配置中，并把路径改成当前机器上的实际绝对路径：

```json
{
  "mcpServers": {
    "elasticsearch-logs": {
      "command": "python",
      "args": ["D:\\pyProject\\esmcp\\es_mcp_server.py"],
      "env": {
        "ES_URLS": "10.128.100.97:9200,10.128.100.98:9200,10.128.100.99:9200",
        "ES_USERNAME": "elastic",
        "ES_PASSWORD": "your-password"
      }
    }
  }
}
```

## 使用示例

- “列出最近的日志索引”
- “在 `app-logs-*` 中查询最近一小时包含 NullPointerException 的日志”
- “筛选 `service.name.keyword=order-service` 且 `log.level.keyword=ERROR` 的日志”
- “查看 2026-07-31T10:30:00+08:00 前后两分钟的日志”
- “统计最近 24 小时各日志级别数量，并按 1 小时展示趋势”

字段名称以实际 mapping 为准；首次使用建议先调用 `get_index_fields`。