使用说明

OpenSearch MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供与OpenSearch集群的无缝集成。该服务器使人工智能系统能够通过标准化的MCP接口在OpenSearch中搜索、索引、聚合和管理数据。

✨ 多集群支持： 同时连接到多个OpenSearch集群，并根据需要将操作路由到特定集群。

特性

🌐 多集群管理

在单个服务器实例中连接到多个OpenSearch集群
动态地将操作路由到特定集群
具有覆盖功能的默认群集配置
向后兼容单集群设置

🔍 搜索与查询

支持Query DSL的全文搜索
简单查询字符串接口
高级过滤和排序
源字段选择和突出显示
滚动API以获取大型结果集

📊 分析和聚合

度量聚合（平均值、总和、计数等）
桶聚合（术语、日期直方图等）
复杂嵌套聚合
统计分析

📄 文档管理

自动生成ID的索引文档
高通量场景下的批量操作
按ID获取、更新和删除文档
通过解决冲突来提升运营效率

🗂️ 索引管理

创建和删除索引
管理字段映射和索引设置
指数统计和健康监测
别名管理

🏥 集群操作

集群健康和状态监控
节点统计和性能指标
碎片分配信息
版本和构建信息

🤖 AI友好工具

查询生成器提示最佳实践
聚合设计协助
映射优化建议
性能调优建议

快速开始

先决条件

Node.js 18+
开放搜索 集群（本地或远程）
VS Code 在MCP支持下（用于开发）

安装

选项1:VS代码开发

# Clone the repository
git clone <repository-url>
cd opensearch-mcp-server

# Install dependencies
npm install

# Copy environment configuration
cp .env.example .env

# Edit configuration
nano .env

# Build the project
npm run build

# Start the server
npm start

选项2:Linux服务器部署

# Make installation script executable
chmod +x install-linux.sh

# Run installation (requires sudo)
sudo ./install-linux.sh

# Edit configuration
sudo nano /etc/opensearch-mcp-server/config

# Restart service
sudo systemctl restart opensearch-mcp

选项3：Docker部署

# Quick start with Docker Compose
./docker-deploy.sh start

# Or manually
docker-compose up -d

配置

多集群设置

服务器支持同时连接到多个OpenSearch集群。您可以通过两种方式配置集群：

选项1：多集群JSON配置

使用 OPENSEARCH_CLUSTERS 带有JSON字符串的环境变量：

变量	描述	必填
`OPENSEARCH_CLUSTERS`	具有命名集群配置的JSON对象	✅
`OPENSEARCH_DEFAULT_CLUSTER`	未在工具调用中指定的默认群集名称	❌

例子：

{
  "OPENSEARCH_CLUSTERS": "{\"production\":{\"node\":\"https://prod-cluster:9200\",\"auth\":{\"username\":\"admin\",\"password\":\"secret\"}},\"staging\":{\"node\":\"https://staging-cluster:9200\",\"auth\":{\"username\":\"admin\",\"password\":\"secret\"}}}",
  "OPENSEARCH_DEFAULT_CLUSTER": "production"
}

选项2：传统单集群配置

为了向后兼容，请使用单独的环境变量（自动创建“默认”集群）：

变量	描述	默认值	必填
`OPENSEARCH_URL`	OpenSearch集群端点	`https://localhost:9200`	✅
`OPENSEARCH_USERNAME`	身份验证用户名	`admin`	✅
`OPENSEARCH_PASSWORD`	身份验证密码	`admin`	✅
`OPENSEARCH_API_KEY`	替代API密钥验证	-	❌
`OPENSEARCH_REJECT_UNAUTHORIZED`	SSL证书验证	`true`	❌
`OPENSEARCH_CA_CERT_PATH`	CA证书的路径	-	❌
`OPENSEARCH_REQUEST_TIMEOUT`	请求超时（ms）	`30000`	❌
`OPENSEARCH_DEFAULT_INDEX`	默认索引模式	-	❌
`OPENSEARCH_INDEX_PREFIX`	索引名称前缀	-	❌

VS代码配置

多集群示例

添加到您的VS代码 mcp.json:

{
  "servers": {
    "opensearch-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./build/index.js"],
      "env": {
        "OPENSEARCH_CLUSTERS": "{\"production\":{\"node\":\"https://prod-cluster:9200\",\"auth\":{\"username\":\"admin\",\"password\":\"secret\"},\"ssl\":{\"rejectUnauthorized\":false}},\"staging\":{\"node\":\"https://staging-cluster:9200\",\"auth\":{\"username\":\"admin\",\"password\":\"secret\"},\"ssl\":{\"rejectUnauthorized\":false}}}",
        "OPENSEARCH_DEFAULT_CLUSTER": "production"
      }
    }
  }
}

单集群（遗留）示例

{
  "servers": {
    "opensearch-mcp-server": {
      "type": "stdio",
      "command": "node",
      "args": ["./build/index.js"],
      "env": {
        "OPENSEARCH_URL": "https://your-opensearch-cluster:9200",
        "OPENSEARCH_USERNAME": "your-username",
        "OPENSEARCH_PASSWORD": "your-password"
      }
    }
  }
}

api参考

群集管理

`opensearch_list_clusters`

列出所有可用的OpenSearch集群和默认集群。

退货： 群集名称和默认群集配置列表。

搜索工具

`opensearch_search`

使用Query DSL或简单的查询字符串搜索文档。

参数：

cluster （字符串，可选）：要查询的群集名称（如果未指定，则使用默认值）
index （字符串，可选）：索引名称或模式
query （对象，可选）：OpenSearch查询DSL对象
q （string，可选）：简单查询字符串
size （number）：结果数（默认值：10，最大值：10000）
from （数字）：分页偏移量（默认值：0）
sort （string | array | object）：排序规范
_source （boolean | string | array）：源字段过滤
highlight （对象）：突出显示配置

例子：

{
  "name": "opensearch_search",
  "arguments": {
    "index": "logs-*",
    "query": {
      "match": {
        "message": "error"
      }
    },
    "size": 20,
    "sort": [{ "@timestamp": "desc" }]
  }
}

`opensearch_aggregate`

执行聚合以进行分析和报告。

参数：

cluster （字符串，可选）：群集名称（如果未指定，则使用默认值）
index （string）：要聚合的索引名称
aggregations （对象）：聚合规范
query （对象，可选）：聚合前过滤查询
size （数字）：要返回的文档点击数（默认值：0）

例子：

{
  "name": "opensearch_aggregate",
  "arguments": {
    "index": "app-logs",
    "aggregations": {
      "status_codes": {
        "terms": {
          "field": "status_code",
          "size": 10
        }
      },
      "avg_response_time": {
        "avg": {
          "field": "response_time"
        }
      }
    }
  }
}

文档管理工具

`opensearch_index_document`

为单个文档建立索引。

参数：

cluster （字符串，可选）：群集名称（如果未指定，则使用默认值）
index （string）：目标索引名称
id （字符串，可选）：文档ID（如果省略，则自动生成）
document （object）：文档数据
refresh （boolean|string）：刷新策略

例子：

{
  "name": "opensearch_index_document",
  "arguments": {
    "index": "user-events",
    "document": {
      "user_id": "12345",
      "event": "login",
      "timestamp": "2024-01-15T10:30:00Z",
      "ip_address": "192.168.1.100"
    },
    "refresh": true
  }
}

`opensearch_bulk_index`

执行批量操作以实现高吞吐量。

参数：

operations （array）：批量操作对象数组
refresh （boolean|string）：刷新策略

例子：

{
  "name": "opensearch_bulk_index",
  "arguments": {
    "operations": [
      { "index": { "_index": "logs", "_id": "1" } },
      { "message": "First log entry", "level": "info" },
      { "index": { "_index": "logs", "_id": "2" } },
      { "message": "Second log entry", "level": "warn" }
    ],
    "refresh": "wait_for"
  }
}

索引管理工具

`opensearch_create_index`

使用设置和映射创建新索引。

参数：

index （string）：索引名称
settings （对象，可选）：索引设置
mappings （对象，可选）：字段映射

例子：

{
  "name": "opensearch_create_index",
  "arguments": {
    "index": "application-logs",
    "settings": {
      "index": {
        "number_of_shards": 2,
        "number_of_replicas": 1
      }
    },
    "mappings": {
      "properties": {
        "timestamp": { "type": "date" },
        "level": { "type": "keyword" },
        "message": { "type": "text" },
        "service": { "type": "keyword" }
      }
    }
  }
}

群集管理工具

`opensearch_cluster_health`

获取群集运行状况和状态信息。

参数：

index （字符串，可选）：要检查的特定索引
level （string）：细节级别（集群、索引、分片）
wait_for_status （字符串，可选）：等待特定状态
timeout （string）：等待操作超时

例子：

{
  "name": "opensearch_cluster_health",
  "arguments": {
    "level": "indices",
    "wait_for_status": "yellow",
    "timeout": "30s"
  }
}

高级用法

查询构建提示

该服务器包括AI友好的提示，以帮助构建复杂的查询：

查询生成器

{
  "name": "opensearch_query_builder",
  "arguments": {
    "search_terms": "error authentication failed",
    "index_pattern": "security-logs-*",
    "filters": "{\"range\": {\"@timestamp\": {\"gte\": \"now-1h\"}}}"
  }
}

聚合生成器

{
  "name": "opensearch_aggregation_builder",
  "arguments": {
    "metric_type": "date_histogram",
    "field_name": "@timestamp",
    "index_pattern": "metrics-*"
  }
}

性能优化

搜索性能

使用特定的索引模式而不是通配符
限制 size 大型结果集的参数
使用 _source 过滤以减少网络开销
使用实现正确的分页 from 和 size

索引性能

对多个文档使用批量操作
设置适当的刷新间隔
考虑高吞吐量场景的异步刷新策略

聚合性能

使用 size: 0 当只需要聚合时跳过文档点击
为聚合字段实现适当的字段映射
为日期直方图使用适当的桶大小

部署场景

VS代码开发

非常适合在人工智能的帮助下进行开发、测试和交互式数据探索。

设置：

安装依赖项 npm install
配置 .env 文件
添加到VS代码 mcp.json
构建并运行 npm run build && npm start

Linux服务器生产

非常适合具有适当服务管理、日志记录和监控的生产环境。

特征：

系统化服务管理
开机时自动启动
结构化日志记录
资源限制和安全策略
配置管理

管理层：

# Service management
sudo systemctl start opensearch-mcp
sudo systemctl status opensearch-mcp
sudo journalctl -u opensearch-mcp -f

# Using management script
./manage-server.sh status
./manage-server.sh logs 100
./manage-server.sh restart

Docker容器

最适合容器化部署、开发环境和云平台。

特征：

包含完整的OpenSearch堆栈
可通过环境变量进行配置
健康检查和监测
卷持久性
网络隔离

用途：

# Development setup
./docker-deploy.sh start

# Production deployment
docker-compose -f docker-compose.prod.yml up -d

# Monitoring
./docker-deploy.sh logs opensearch-mcp-server
./docker-deploy.sh status

安全考虑

认证

始终对OpenSearch集群使用强密码
考虑对编程访问进行API密钥身份验证
实施适当的用户角色和权限

网络安全

对OpenSearch连接使用HTTPS/TLS
在生产环境中验证SSL证书(OPENSEARCH_REJECT_UNAUTHORIZED=true)
实施网络防火墙和访问控制
使用VPN或专用网络访问群集

数据保护

在OpenSearch中启用审核日志记录
为敏感数据实施现场级安全
使用索引级权限和访问控制
定期备份和灾难恢复程序

故障排除

常见问题

连接问题

# Check OpenSearch cluster health
curl -k -u admin:password https://your-cluster:9200/_cluster/health

# Verify network connectivity
telnet your-cluster 9200

# Check SSL certificate issues
openssl s_client -connect your-cluster:9200 -showcerts

身份验证失败

验证配置中的用户名和密码
检查OpenSearch中的用户权限
确保API密钥有效并且具有适当的权限

性能问题

监控群集资源使用情况
检查索引碎片分配
查看查询模式以寻找优化机会
实现正确的字段映射

调试

发展模式

# Enable debug logging
export DEBUG=opensearch-mcp:*
npm run dev

# Use VS Code debugger
# Press F5 in VS Code with proper launch configuration

生产监控

# Check service logs
journalctl -u opensearch-mcp -f

# Monitor cluster health
./manage-server.sh status

# Check resource usage
htop
iostat -x 1

贡献

复刻仓库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
添加新功能的测试
运行测试(npm test)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

文档：参见 /docs 详细指南目录
问题：在GitHub Issues上报告错误和请求功能
讨论：在GitHub上加入社区讨论

使用说明

OpenSearch MCP服务器

特性

🌐 多集群管理

🔍 搜索与查询

📊 分析和聚合

📄 文档管理

🗂️ 索引管理

🏥 集群操作

🤖 AI友好工具

快速开始

先决条件

安装

选项1:VS代码开发

选项2:Linux服务器部署

选项3：Docker部署

配置

多集群设置

选项1：多集群JSON配置

选项2：传统单集群配置

VS代码配置

多集群示例

单集群（遗留）示例

api参考

群集管理

opensearch_list_clusters

搜索工具

opensearch_search

opensearch_aggregate

文档管理工具

opensearch_index_document

opensearch_bulk_index

索引管理工具

opensearch_create_index

群集管理工具

opensearch_cluster_health

高级用法

查询构建提示

查询生成器

聚合生成器

性能优化

搜索性能

索引性能

聚合性能

部署场景

VS代码开发

Linux服务器生产

Docker容器

安全考虑

认证

网络安全

数据保护

故障排除

常见问题

连接问题

身份验证失败

性能问题

调试

发展模式

生产监控

贡献

许可证

支持

相关项目

相关 MCP

多集群Kubernetes管理服务

Kubernetes 多集群管理服务

数据搜索协议服务器

多集群管理MCP服务器

Kubernetes 自然语言管理 MCP 服务器

Redis自然语言接口服务器

`opensearch_list_clusters`

`opensearch_search`

`opensearch_aggregate`

`opensearch_index_document`

`opensearch_bulk_index`

`opensearch_create_index`

`opensearch_cluster_health`