MCP Es

🚀 Elasticsearch MCP Server

本倉庫包含用於研究和評估的實驗性功能，尚未達到生產就緒狀態。藉助模型上下文協議（MCP），可直接從任何 MCP 客戶端（如 Claude Desktop）連接到你的 Elasticsearch 數據。此服務器使用模型上下文協議將代理連接到你的 Elasticsearch 數據，允許你通過自然語言對話與 Elasticsearch 索引進行交互。

🚀 快速開始

本項目允許你通過 MCP 客戶端與 Elasticsearch 數據進行自然語言交互。以下是使用本項目的基本步驟：

1. 確保你已具備所需的先決條件。
2. 選擇合適的安裝和設置方式。
3. 開始與 Elasticsearch 數據進行對話。

✨ 主要特性

可用工具

• list_indices：列出所有可用的 Elasticsearch 索引。
• get_mappings：獲取特定 Elasticsearch 索引的字段映射。
• search：使用提供的查詢 DSL 執行 Elasticsearch 搜索。
• get_shards：獲取所有或特定索引的分片信息。

工作原理

1. MCP 客戶端分析你的請求，並確定需要執行哪些 Elasticsearch 操作。
2. MCP 服務器執行這些操作（列出索引、獲取映射、執行搜索）。
3. MCP 客戶端處理結果並以用戶友好的格式呈現。

📦 安裝指南

使用發佈的 NPM 包

💡 使用建議 使用 Elasticsearch MCP Server 最簡單的方法是通過發佈的 npm 包。

1. 配置 MCP 客戶端
   • 打開你的 MCP 客戶端。查看 MCP 客戶端列表，這裡我們以配置 Claude Desktop 為例。
   • 轉到 設置 > 開發者 > MCP 服務器。
   • 點擊 編輯配置，並添加一個新的 MCP 服務器，配置如下：

{
    "mcpServers": {
        "elasticsearch - mcp - server": {
            "command": "npx",
            "args": [
                "-y",
                "@elastic/mcp-server-elasticsearch"
            ],
            "env": {
                "ES_URL": "your-elasticsearch-url",
                "ES_API_KEY": "your-api-key"
            }
        }
    }
}

2. 開始對話
   • 在你的 MCP 客戶端中打開一個新的對話。
   • MCP 服務器應會自動連接。
   • 現在你可以詢問有關 Elasticsearch 數據的問題。

配置選項

Elasticsearch MCP Server 支持以下配置選項以連接到你的 Elasticsearch：

⚠️ 重要提示 你必須提供 API 密鑰或用戶名和密碼進行身份驗證。

本地開發

⚠️ 重要提示 如果你想修改或擴展 MCP 服務器，請按照以下本地開發步驟操作。

1. 使用正確的 Node.js 版本

nvm use

2. 安裝依賴項

npm install

3. 構建項目

npm run build

4. 在 Claude Desktop 應用中本地運行
   • 打開 Claude Desktop 應用。
   • 轉到 設置 > 開發者 > MCP 服務器。
   • 點擊 編輯配置，並添加一個新的 MCP 服務器，配置如下：

{
    "mcpServers": {
        "elasticsearch - mcp - server - local": {
            "command": "node",
            "args": [
                "/path/to/your/project/dist/index.js"
            ],
            "env": {
                "ES_URL": "your-elasticsearch-url",
                "ES_API_KEY": "your-api-key"
            }
        }
    }
}

5. 使用 MCP 檢查器進行調試

ES_URL=your-elasticsearch-url ES_API_KEY=your-api-key npm run inspector

這將啟動 MCP 檢查器，允許你調試和分析請求。你應該會看到：

Starting MCP inspector...
Proxy server listening on port 3000

🔍 MCP Inspector is up and running at http://localhost:5173 🚀

💻 使用示例

基礎用法

你可以在 MCP 客戶端中嘗試以下自然語言查詢：

• "What indices do I have in my Elasticsearch cluster?"（我的 Elasticsearch 集群中有哪些索引？）
• "Show me the field mappings for the 'products' index."（顯示 'products' 索引的字段映射。）
• "Find all orders over $500 from last month."（查找上個月超過 500 美元的所有訂單。）
• "Which products received the most 5 - star reviews?"（哪些產品獲得了最多的五星評價？）

📚 詳細文檔

貢獻

我們歡迎社區的貢獻！有關如何貢獻的詳細信息，請參閱 貢獻指南。

故障排除

• 確保你的 MCP 配置正確。
• 驗證你的 Elasticsearch URL 可從你的機器訪問。
• 檢查你的身份驗證憑據（API 密鑰或用戶名/密碼）是否具有必要的權限。
• 如果你使用自定義 CA 進行 SSL/TLS 連接，請驗證證書路徑是否正確且文件可讀。
• 查看終端輸出以獲取錯誤消息。

如果你遇到問題，請隨時在 GitHub 倉庫上打開一個問題。

🔧 技術細節

工作原理

1. MCP 客戶端分析你的請求，並確定需要執行哪些 Elasticsearch 操作。
2. MCP 服務器執行這些操作（列出索引、獲取映射、執行搜索）。
3. MCP 客戶端處理結果並以用戶友好的格式呈現。

安全最佳實踐

⚠️ 重要提示 避免使用集群管理員權限。創建具有有限範圍的專用 API 密鑰，並在索引級別應用細粒度的訪問控制，以防止未經授權的數據訪問。

你可以創建一個具有最小權限的專用 Elasticsearch API 密鑰來控制對數據的訪問：

POST /_security/api_key
{
    "name": "es-mcp-server-access",
    "role_descriptors": {
        "mcp_server_role": {
            "cluster": [
                "monitor"
            ],
            "indices": [
                {
                    "names": [
                        "index-1",
                        "index-2",
                        "index-pattern-*"
                    ],
                    "privileges": [
                        "read",
                        "view_index_metadata"
                    ]
                }
            ]
        }
    }
}

📄 許可證

本項目採用 Apache 許可證 2.0 版。