ifc-es-mcp-server

Elasticsearch MCP Server for IFC logging system.

功能特性

• 🔍 索引管理 - 列出可用索引、查看字段映射
• 📊 日志搜索 - 按时间范围、关键词、日志级别、服务名等条件搜索日志
• 📈 聚合统计 - 对日志字段进行聚合分析（如错误码分布、级别分布等）
• 🔗 链路追踪 - 通过 trace_id 追踪分布式调用的全链路日志

安装

从 PyPI 安装（推荐）

pip install ifc-es-mcp-server

从源码安装

git clone https://github.com/your-username/ifc-es-mcp-server.git
cd ifc-es-mcp-server
pip install -e .

配置

创建 .env 文件或设置以下环境变量：

# Elasticsearch 连接配置
ES_HOSTS=http://localhost:9200
ES_USERNAME=
ES_PASSWORD=
ES_VERIFY_CERTS=false
ES_REQUEST_TIMEOUT=30
ES_MAX_RETRIES=3

# 查询默认值
ES_DEFAULT_SIZE=20
ES_MAX_SIZE=50

# 字段配置（可选）
ES_LEVEL_FIELDS=level.keyword,level
ES_MESSAGE_FIELDS=log_message,logmsg
ES_TRACE_FIELDS=tid
ES_SERVICE_FIELDS=serviceName.keyword,serviceName
ES_SOURCE_FIELDS=logtime,hostIP,level,serviceName,tid,thread,class,line,log_message

使用方式

1. 命令行启动

# 使用 stdio 传输（适用于 Claude Desktop 等客户端）
ifc-es-mcp-server

# 或使用 SSE 传输
ifc-es-mcp-server --transport sse --port 8080

2. 在 Claude Desktop 中配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "elasticsearch": {
      "command": "ifc-es-mcp-server",
      "env": {
        "ES_HOSTS": "http://your-es-host:9200",
        "ES_USERNAME": "your-username",
        "ES_PASSWORD": "your-password"
      }
    }
  }
}

3. 在 Claude Code 中配置

{
  "mcpServers": {
    "elasticsearch": {
      "command": "ifc-es-mcp-server",
      "env": {
        "ES_HOSTS": "http://your-es-host:9200",
        "ES_USERNAME": "your-username",
        "ES_PASSWORD": "your-password"
      }
    }
  }
}

工具说明

list_indices

列出可用的 ES 索引。

参数：

• pattern (str): 索引名匹配模式，支持通配符，默认 *
• limit (int): 返回数量上限，默认 50，最大 200

get_index_mapping

查看索引的字段映射，了解有哪些字段可用。

参数：

• index (str): 索引名（支持通配符）

search_logs

在 ES 中按时间范围 + 关键词 + 日志级别查询日志。

参数：

• index (str): 索引名，支持通配符
• query (str, optional): 关键词，默认在 log_message 字段匹配
• level (str, optional): 日志级别过滤，如 ERROR/WARN/INFO
• service_names (List[str], optional): 按服务名过滤
• time_from (str): 起始时间，默认 now-10m
• time_to (str): 结束时间，默认 now
• match_type (str): 匹配方式，match/match_phrase/wildcard
• size (int): 返回条数，默认 20，硬上限 50
• sort_order (str): 排序方式，desc/asc

aggregate_logs

对日志做字段聚合统计。

参数：

• index (str): 索引名，支持通配符
• field (str): 要聚合的字段名
• time_field (str): 时间字段名，默认 @timestamp
• time_from (str): 起始时间，默认 now-1h
• time_to (str): 结束时间，默认 now
• query (str, optional): 聚合前先过滤的关键词
• level (str, optional): 聚合前先按日志级别过滤
• service_names (List[str], optional): 聚合前先按服务名过滤
• top_n (int): 返回分组数，默认 10，上限 100

get_trace_detail

通过 trace_id 追踪分布式调用的全链路日志。

参数：

• trace_id (str): 链路追踪 ID
• index (str): 索引名，支持通配符
• trace_field (str, optional): trace_id 字段名，不传则自动探测
• service_field (str, optional): 服务名字段名，不传则自动探测
• time_field (str): 时间字段名，默认 @timestamp
• time_from (str): 起始时间，默认 now-24h
• time_to (str): 结束时间，默认 now
• size (int): 返回 span 上限，默认 500

开发

环境准备（推荐使用 uv）

# 安装 uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 同步依赖（自动创建虚拟环境）
uv sync

# 激活虚拟环境
source .venv/bin/activate  # Linux/Mac
# 或 .venv\Scripts\activate  # Windows

运行测试

uv run pytest

代码格式化

uv run ruff format .
uv run ruff check .

构建包

uv build

发布到 PyPI

# 使用 uv 发布
uv publish

# 或使用 twine（如果需要更细粒度控制）
uv tool install twine
twine upload dist/*

# 上传到 TestPyPI（测试）
twine upload --repository testpypi dist/*

环境变量说明

变量名	默认值	说明
ES_HOSTS	http://localhost:9200	ES 集群地址，多个用逗号分隔
ES_USERNAME	""	ES 用户名
ES_PASSWORD	""	ES 密码
ES_VERIFY_CERTS	false	是否验证 SSL 证书
ES_REQUEST_TIMEOUT	30	请求超时时间（秒）
ES_MAX_RETRIES	3	最大重试次数
ES_DEFAULT_SIZE	20	默认返回条数
ES_MAX_SIZE	50	最大返回条数
ES_LEVEL_FIELDS	level.keyword,level	日志级别字段候选列表
ES_MESSAGE_FIELDS	log_message,logmsg	消息字段候选列表
ES_TRACE_FIELDS	tid	Trace ID 字段候选列表
ES_SERVICE_FIELDS	serviceName.keyword,serviceName	服务名字段候选列表
ES_SOURCE_FIELDS	logtime,hostIP,level,serviceName,tid,thread,class,line,log_message	默认返回字段列表

License

MIT