elasticsearch-client-mcp-py 1.0.5

MCP Server for Elasticsearch - schema discovery, search, CRUD operations

Elasticsearch Client MCP

MCP Server for Elasticsearch - 支持 ES 6/7/8 版本，连接管理，搜索和 CRUD 操作。

配置

MCP 配置（~/.claude/settings.json）

在 mcpServers 中配置连接信息：

{
  "mcpServers": {
    "elasticsearch-client": {
      "command": "uvx",
      "args": ["elasticsearch-client-mcp-py"],
      "env": {
        "ES_CONNECTIONS": "[{\"name\":\"my_es\",\"env\":\"prod\",\"url\":\"http://your-es-host:9200\",\"username\":\"elastic\",\"password\":\"your_password\"}]"
      },
      "type": "stdio"
    }
  }
}

ES_CONNECTIONS 格式：

[
  {
    "name": "连接名称",
    "env": "环境(dev/prod/test)",
    "description": "可选描述",
    "url": "http://es-host:9200",
    "username": "elastic",
    "password": "密码",
    "safety": {
      "read_only": false,
      "max_search_size": 100,
      "confirm_delete": false,
      "allow_delete_index": true,
      "allow_create_index": true
    }
  }
]

profile.json - 权限配置

权限配置存储在 ~/.config/elasticsearch-client-mcp/profile.json：

{
  "_last_connection": "prod_finance",
  "_connection_cache": {},
  "_envs": {
    "prod": {
      "safety": {
        "read_only": true,
        "max_search_size": 50,
        "confirm_delete": true,
        "allow_delete_index": false,
        "allow_create_index": false,
        "risk_check": true
      }
    },
    "dev": {
      "safety": {
        "read_only": false,
        "max_search_size": 100,
        "confirm_delete": false,
        "allow_delete_index": true,
        "allow_create_index": true,
        "risk_check": true
      }
    }
  }
}

safety 配置说明：

• read_only: 只读模式，拒绝写操作
• max_search_size: 最大搜索条数
• confirm_delete: 删除时需要确认
• allow_delete_index: 是否允许删除索引
• allow_create_index: 是否允许创建索引

优先级：

1. MCP env 中的 safety 配置（优先）
2. profile.json 中对应 env 的 safety

Tools

• list_connections - 列出所有连接
• get_current_connection - 获取当前连接
• select_connection - 选择连接
• es_search - 搜索文档 (from/size 分页)
• es_scroll - 滚动查询
• es_scroll_next - 滚动下一页
• es_scroll_clear - 清除滚动
• es_index_doc - 索引文档
• es_update_doc - 更新文档
• es_delete_doc - 删除文档
• es_bulk - 批量操作
• es_create_index - 创建索引
• es_delete_index - 删除索引
• es_index_exists - 检查索引是否存在
• es_get_index_mapping - 获取索引 mapping
• es_list_indices - 列出所有索引

版本兼容

自动检测 ES 版本 (6/7/8)，适配对应的 API。

版本检测流程

select_connection()
    │
    ├─→ HTTP 直接获取 / → 解析 version.number
    │   (兼容所有版本，不依赖 elasticsearch-py)
    │
    └─→ 缓存到 profile.json
            │
            └─→ _session_state.es_version

版本路由架构

create_ops(config, es_version)
    │
    ├─→ ES 6 → ES6Ops (原生 HTTP)
    │           不依赖 elasticsearch-py 库
    │
    ├─→ ES 7 → ES7Ops (elasticsearch-py 7.x)
    │
    └─→ ES 8+ → ES8Ops (elasticsearch-py 8.x)

版本差异处理

操作	ES 6	ES 7	ES 8+
_type	已废弃，搜索时删除	支持	移除
认证	http_auth	http_auth	basic_auth
Content-Type	application/json	application/json	application/json
搜索实现	原生 HTTP	elasticsearch-py	elasticsearch-py

核心文件

src/elasticsearch_client_mcp/
├── client.py              # 版本操作类 ES6Ops/ES7Ops/ES8Ops
├── tools/
│   ├── connections.py     # 连接管理、版本路由
│   └── es_operations.py   # 统一操作入口
└── config/
    └── config.py          # 配置加载、版本缓存

安装

uv pip install -e .