OpenSearch Logs MCP Server
OpenSearch 日志 MCP 服务器
MCP (Model Context Protocol) 服务器,用于查询 OpenSearch 中的 OpenTelemetry 日志。支持开发 (dev) 和生产 (prod) 环境。
架构
该服务器遵循 SOLID 原则和整洁架构 (Clean Architecture):
src/
├── index.ts # Entry point
├── server.ts # MCP Server setup
├── config/
│ └── environments.ts # Environment configuration
├── types/
│ └── index.ts # Type definitions
├── services/
│ ├── opensearch-client.ts # HTTP client for OpenSearch
│ └── log-search.service.ts # Business logic
├── tools/
│ ├── tool-definitions.ts # Tool schemas
│ └── tool-handlers.ts # Tool execution
└── utils/
├── query-builder.ts # Query construction (Builder pattern)
└── time-range.ts # Time utilities应用原则
单一职责原则 (SRP):每个模块都有单一的职责
开闭原则 (OCP):无需修改现有代码即可轻松添加新工具
依赖倒置原则 (DIP):服务依赖于抽象(接口)
构建者模式 (Builder Pattern):使用
QueryBuilder进行流畅的查询构建
Related MCP server: datadog-logs-mcp
安装
cd Tools/mcp-opensearch-logs
npm install
npm run buildCursor 配置
将以下内容添加到你的 Cursor 配置 (~/.cursor/mcp.json) 中:
{
"mcpServers": {
"opensearch-logs": {
"command": "node",
"args": ["/ruta/al/proyecto/Tools/mcp-opensearch-logs/dist/index.js"],
"env": {
"OPENSEARCH_DEV_USERNAME": "tu-usuario-dev",
"OPENSEARCH_DEV_PASSWORD": "tu-password-dev",
"OPENSEARCH_PROD_USERNAME": "tu-usuario-prod",
"OPENSEARCH_PROD_PASSWORD": "tu-password-prod"
}
}
}
}可用工具
search_logs
使用 Lucene 语法的自由搜索。
参数 | 类型 | 必填 | 描述 | ||||
environment |
|
| ✅ | 要查询的环境 | |||
query | string | ✅ | Lucene 语法查询 | ||||
timeRange |
|
|
|
|
| ❌ | 时间范围 (默认: 1h) |
size | number | ❌ | 最大结果数 (默认: 50, 最大: 200) |
示例:
"搜索过去一小时内 dev 环境中包含 'error' 的日志"
"搜索过去 6 小时内 prod 环境中状态为 500 的日志"
search_by_trace
搜索 OpenTelemetry 追踪的所有日志。
参数 | 类型 | 必填 | 描述 | |
environment |
|
| ✅ | 要查询的环境 |
traceId | string | ✅ | 追踪 ID | |
size | number | ❌ | 最大结果数 (默认: 100) |
示例:
"获取 dev 环境中 trace abc123 的所有日志"
search_by_service
按服务名称过滤日志。
参数 | 类型 | 必填 | 描述 | ||||
environment |
|
| ✅ | 要查询的环境 | |||
serviceName | string | ✅ | 服务名称 | ||||
level |
|
|
|
|
| ❌ | 日志级别 |
query | string | ❌ | 附加查询 | ||||
timeRange | string | ❌ | 时间范围 | ||||
size | number | ❌ | 最大结果数 |
示例:
"搜索 prod 环境中 stori-ios 服务的日志"
"获取 dev 环境中 stori-ios 服务的错误日志"
search_errors
搜索 ERROR 或更高级别(severityNumber >= 17)的日志。
参数 | 类型 | 必填 | 描述 | |
environment |
|
| ✅ | 要查询的环境 |
serviceName | string | ❌ | 按服务过滤 | |
query | string | ❌ | 附加查询 | |
timeRange | string | ❌ | 时间范围 | |
size | number | ❌ | 最大结果数 |
示例:
"获取 prod 环境中过去一小时的错误"
"搜索 dev 环境中与 KYC 相关的错误"
get_field_values
获取字段的最常见值(聚合)。
参数 | 类型 | 必填 | 描述 | |
environment |
|
| ✅ | 要查询的环境 |
field | string | ✅ | 要聚合的字段 | |
size | number | ❌ | 唯一值的最大数量 (默认: 20) |
示例:
"prod 环境中 'event' 字段有哪些值?"
"获取 dev 环境中最常见的错误类型"
search_by_field
按特定字段和值进行搜索。
参数 | 类型 | 必填 | 描述 | |
environment |
|
| ✅ | 要查询的环境 |
field | string | ✅ | 字段名称 | |
value | string | ✅ | 要搜索的值 | |
timeRange | string | ❌ | 时间范围 | |
size | number | ❌ | 最大结果数 |
示例:
"搜索 prod 环境中 transactionId=abc123 的日志"
get_mapping
获取索引的字段映射。
参数 | 类型 | 必填 | 描述 | |
environment |
|
| ✅ | 要查询的环境 |
示例:
"prod 日志中有哪些可用字段?"
get_sample_log
获取示例日志以查看结构。
参数 | 类型 | 必填 | 描述 | |
environment |
|
| ✅ | 要查询的环境 |
示例:
"给我一个 prod 日志示例以查看其结构"
Lucene 搜索语法
query 字段支持完整的 Lucene 语法:
语法 | 描述 | 示例 |
| 在任何字段中搜索 |
|
| 在特定字段中搜索 |
|
| 通配符 |
|
| 两个词都包含 |
|
| 包含任意一个词 |
|
| 排除词 |
|
| 范围 |
|
| 精确匹配 |
|
时间范围
值 | 描述 |
| 最近 15 分钟 |
| 最近一小时 (默认) |
| 最近 6 小时 |
| 最近 24 小时 |
| 最近 7 天 |
开发
# Desarrollo con watch mode
npm run dev
# Build
npm run build
# Lint
npm run lintOpenTelemetry 日志结构
日志遵循 OpenTelemetry 模式:
{
"time": "2024-01-15T10:30:00.000Z",
"severityText": "ERROR",
"severityNumber": 17,
"body": "Error message",
"attributes": {
"event": "kyc_error",
"kycFlow": "creditL1",
"transactionId": "abc123"
},
"resource": {
"service.name": "stori-ios",
"service.version": "1.0.0"
}
}Available Tools
8 toolsget_field_valuesB
Get the most common values for a specific field. Useful for discovering available services, log levels, or other field values.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) | |
| field | Yes | The field to get values for. Examples: 'service.name', 'level', 'host.name' | |
| size | No | Maximum number of unique values to return (default: 20) |
get_mappingA
Get the field mapping for the index. Useful for discovering available fields and their types.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) |
get_sample_logB
Get a single sample log entry to see the structure and available fields.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) |
search_by_fieldC
Search logs by a specific field and value.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) | |
| field | Yes | The field name to search. Examples: 'user_id', 'request_id', 'endpoint' | |
| value | Yes | The value to search for | |
| timeRange | No | Time range to search within | |
| size | No | Maximum number of results to return (default: 50) |
search_by_serviceC
Search logs filtered by service name, optionally with additional filters.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) | |
| serviceName | Yes | The service name to filter by | |
| level | No | Log level to filter by | |
| query | No | Additional free-text query to apply | |
| timeRange | No | Time range to search within | |
| size | No | Maximum number of results to return (default: 50) |
search_by_traceA
Search logs by OpenTelemetry trace ID to see all logs related to a specific request/transaction.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) | |
| traceId | Yes | The OpenTelemetry trace ID to search for | |
| size | No | Maximum number of results to return (default: 100) |
search_errorsC
Search for error logs, optionally filtered by service or additional query.
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) | |
| serviceName | No | Optional service name to filter by | |
| query | No | Additional free-text query to apply | |
| timeRange | No | Time range to search within (default: 1h) | |
| size | No | Maximum number of results to return (default: 50) |
search_logsA
Search OpenSearch logs with a free-text query. Supports Lucene query syntax. Examples: 'error AND authentication', 'status:500', 'message:timeout'
| Name | Required | Description | Default |
|---|---|---|---|
| environment | Yes | Environment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android) | |
| query | Yes | Free-text search query using Lucene syntax. Examples: 'error', 'status:500 AND service.name:auth' | |
| timeRange | No | Time range to search within. Defaults to 1h if not specified. | |
| size | No | Maximum number of results to return (default: 50, max: 200) |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
8 tool updates
v1.0.0- First observed
get_field_values - First observed
get_mapping - First observed
get_sample_log - First observed
search_by_field - First observed
search_by_service - First observed
search_by_trace - First observed
search_errors - First observed
search_logs
TDQS
Scored across 8 tools
Most tools have distinct purposes, but there is some overlap between search_by_field, search_by_service, search_errors, and search_logs, which could cause confusion about which to use for specific filtering needs. However, the descriptions clarify their specialized roles, such as search_by_service for service filtering and search_errors for error-specific queries, reducing ambiguity.
All tool names follow a consistent verb_noun pattern with snake_case, such as get_field_values, search_by_trace, and search_logs. This uniformity makes the tool set predictable and easy to understand, enhancing usability for agents.
With 8 tools, the server is well-scoped for log analysis in OpenSearch, covering essential operations like discovery (get_field_values, get_mapping, get_sample_log) and various search methods. Each tool serves a clear purpose without feeling excessive or insufficient for the domain.
The tool set provides strong coverage for log querying and discovery, including field analysis, sample inspection, and multiple search types. A minor gap is the lack of tools for log management operations like deleting or exporting logs, but core workflows for analysis are well-supported.
Maintenance
Related MCP Connectors
Ingest and search LogsLoom logs from coding agents.
Read-only access to Auralogs production logs: search logs, inspect errors, review AI analyses.
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Read LogBrew errors, slow traces, logs, and product analytics, and triage issues with consent.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables searching and analyzing AWS CloudWatch logs with support for configurable log groups, time-based searches, and service-specific log stream filtering.5MIT
- AlicenseAqualityDmaintenanceEnables querying and analyzing Datadog logs through search, aggregation, and index listing.313 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables querying and searching logs from Kibana (ELK stack) via MCP, with support for project-based data views, trace ID correlation, and log expansion.-
- AlicenseAqualityAmaintenanceEnables AI agents to search and analyze SAP Commerce Cloud (CCv2) runtime logs via OpenSearch Dashboards using a session cookie, providing read-only tools for full-text search and error aggregation.3MIT