Metadata-Version: 2.4
Name: elasticsearch-client-mcp-py
Version: 0.6.2
Summary: MCP Server for Elasticsearch - index discovery, mapping, safe search/write execution
Project-URL: Homepage, https://github.com/dong-tech/elasticsearch-client-mcp-py
Project-URL: Repository, https://github.com/dong-tech/elasticsearch-client-mcp-py
Author: dong_tech
License: MIT
Keywords: ai,elasticsearch,llm,mcp,model-context-protocol
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Requires-Dist: elasticsearch>=8.0.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Elasticsearch MCP Server (elasticsearch-client-mcp-py)

Elasticsearch MCP Server：连接与索引发现、mapping、安全执行（搜索/写入由大模型产生 DSL，MCP 只做校验与执行）。

## 环境变量

### 单连接

| 变量 | 说明 |
|------|------|
| `ES_HOSTS` | 单 URL 形式，如 `https://host:9200`（推荐，自动解析 host/port/ssl） |
| `ES_HOST` | 主机，如 localhost（与 ES_PORT 搭配） |
| `ES_PORT` | 端口，默认 9200 |
| `ES_USER` / `ES_USERNAME` | 用户名，可选 |
| `ES_PASSWORD` / `ES_PWD` | 密码，可选 |
| `ES_USE_SSL` | 是否 HTTPS，默认 false（使用 ES_HOSTS 时由 URL 自动判断） |
| `ES_SKIP_PRODUCT_CHECK` | 设为 1/true 时跳过 X-Elastic-Product 校验，兼容 ES 7.x、OpenSearch 等 |

### 多环境（TEST_ES_PROFILES / UAT_ES_PROFILES / PROD_ES_PROFILES）

每项可为：`hosts`（URL）或 `host`+`port`；`user`/`username`、`password`/`pwd`；`use_ssl`、`description`、`name`。Profile 名为 `test_0`, `prod_0` 等。

### 示例：阿里云 Elasticsearch

```bash
# 单连接（注意：阿里云一般为 https，若你写的是 http1 请改为 https）
export ES_HOSTS="https://es-cn-0pp16vs4k000g76xq.elasticsearch.aliyuncs.com:9200"
export ES_USER="elastic"
export ES_PASSWORD="yunkc@123"
```

或使用 profile JSON（如 mcp.json 的 env）：

```json
"PROD_ES_PROFILES": "[{\"hosts\":\"https://es-cn-0pp16vs4k000g76xq.elasticsearch.aliyuncs.com:9200\",\"username\":\"elastic\",\"pwd\":\"yunkc@123\"}]"
```

### 安全

| 变量 | 默认 | 说明 |
|------|------|------|
| `ES_READ_ONLY` | false | 为 true 时仅允许搜索 |
| `ES_MAX_SEARCH_SIZE` | 100 | 单次 search size 上限 |
| `ES_REQUEST_TIMEOUT` | 30 | 请求超时(秒) |

## 安装与运行

```bash
uv sync && uv run python -m elasticsearch_client_mcp
# 或
elasticsearch-client-mcp-py
```

## 工具

| 工具 | 说明 |
|------|------|
| `list_connections` | 列出可用连接 |
| `list_indices` | 列出索引（支持 pattern） |
| `get_mapping` | 指定索引的 mapping |
| `analyze_request` | 分析请求（读/写/危险），不执行 |
| `execute_request` | 执行单条请求（method+path+body）；写操作需 confirm |

## License

MIT
