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/INFOservice_names(List[str], optional): 按服务名过滤time_from(str): 起始时间,默认now-10mtime_to(str): 结束时间,默认nowmatch_type(str): 匹配方式,match/match_phrase/wildcardsize(int): 返回条数,默认 20,硬上限 50sort_order(str): 排序方式,desc/asc
aggregate_logs
对日志做字段聚合统计。
参数:
index(str): 索引名,支持通配符field(str): 要聚合的字段名time_field(str): 时间字段名,默认@timestamptime_from(str): 起始时间,默认now-1htime_to(str): 结束时间,默认nowquery(str, optional): 聚合前先过滤的关键词level(str, optional): 聚合前先按日志级别过滤service_names(List[str], optional): 聚合前先按服务名过滤top_n(int): 返回分组数,默认 10,上限 100
get_trace_detail
通过 trace_id 追踪分布式调用的全链路日志。
参数:
trace_id(str): 链路追踪 IDindex(str): 索引名,支持通配符trace_field(str, optional): trace_id 字段名,不传则自动探测service_field(str, optional): 服务名字段名,不传则自动探测time_field(str): 时间字段名,默认@timestamptime_from(str): 起始时间,默认now-24htime_to(str): 结束时间,默认nowsize(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
Metadata
Release files for ifc-es-mcp-server 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ifc_es_mcp_server-0.1.3.tar.gz | 77.6 kB | Without provenance | Details for ifc_es_mcp_server-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ifc_es_mcp_server-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for ifc_es_mcp_server-0.1.3-py3-none-any.whl |
Total release size: 89.9 kB
Release files / ifc_es_mcp_server-0.1.3.tar.gz
| Download URL | ifc_es_mcp_server-0.1.3.tar.gz |
|---|---|
| Size | 77.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7bd0f3d560df313a76d393ae12dbf61a4a0aafea108ce6e3dddca81dbffae7e4
|
|
BLAKE2b-256 checksum How to use checksums |
21ad2b3566bf4da00613f8bf31695d5fb080a9e50dba878218bb729a1c2644d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Release files / ifc_es_mcp_server-0.1.3-py3-none-any.whl
| Download URL | ifc_es_mcp_server-0.1.3-py3-none-any.whl |
|---|---|
| Size | 12.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57737782f087054997fc32ac2bf6843b14c9dba14006bba834c7962dfd070354
|
|
BLAKE2b-256 checksum How to use checksums |
936886535689e058ebbfc4cc88e5e6f9be58064398ccb7267ad762a0499d217d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.6.9
|
Security for ifc-es-mcp-server 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.