Skip to main content
Glama
OpenSearch Logs MCP Server

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 build

Cursor 配置

将以下内容添加到你的 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

dev

prod

✅

要查询的环境

query

string

✅

Lucene 语法查询

timeRange

15m

1h

6h

24h

7d

❌

时间范围 (默认: 1h)

size

number

❌

最大结果数 (默认: 50, 最大: 200)

示例:

  • "搜索过去一小时内 dev 环境中包含 'error' 的日志"

  • "搜索过去 6 小时内 prod 环境中状态为 500 的日志"

search_by_trace

搜索 OpenTelemetry 追踪的所有日志。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

traceId

string

✅

追踪 ID

size

number

❌

最大结果数 (默认: 100)

示例:

  • "获取 dev 环境中 trace abc123 的所有日志"

search_by_service

按服务名称过滤日志。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

serviceName

string

✅

服务名称

level

DEBUG

INFO

WARN

ERROR

FATAL

❌

日志级别

query

string

❌

附加查询

timeRange

string

❌

时间范围

size

number

❌

最大结果数

示例:

  • "搜索 prod 环境中 stori-ios 服务的日志"

  • "获取 dev 环境中 stori-ios 服务的错误日志"

search_errors

搜索 ERROR 或更高级别(severityNumber >= 17)的日志。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

serviceName

string

❌

按服务过滤

query

string

❌

附加查询

timeRange

string

❌

时间范围

size

number

❌

最大结果数

示例:

  • "获取 prod 环境中过去一小时的错误"

  • "搜索 dev 环境中与 KYC 相关的错误"

get_field_values

获取字段的最常见值(聚合)。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

field

string

✅

要聚合的字段

size

number

❌

唯一值的最大数量 (默认: 20)

示例:

  • "prod 环境中 'event' 字段有哪些值?"

  • "获取 dev 环境中最常见的错误类型"

search_by_field

按特定字段和值进行搜索。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

field

string

✅

字段名称

value

string

✅

要搜索的值

timeRange

string

❌

时间范围

size

number

❌

最大结果数

示例:

  • "搜索 prod 环境中 transactionId=abc123 的日志"

get_mapping

获取索引的字段映射。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

示例:

  • "prod 日志中有哪些可用字段?"

get_sample_log

获取示例日志以查看结构。

参数

类型

必填

描述

environment

dev

prod

✅

要查询的环境

示例:

  • "给我一个 prod 日志示例以查看其结构"

Lucene 搜索语法

query 字段支持完整的 Lucene 语法:

语法

描述

示例

term

在任何字段中搜索

error

field:value

在特定字段中搜索

event:kyc_error

field:*value*

通配符

errorMessage:*timeout*

AND

两个词都包含

error AND authentication

OR

包含任意一个词

error OR warning

NOT

排除词

NOT debug

[a TO b]

范围

statusCode:[400 TO 499]

"exact phrase"

精确匹配

"connection refused"

时间范围

值

描述

15m

最近 15 分钟

1h

最近一小时 (默认)

6h

最近 6 小时

24h

最近 24 小时

7d

最近 7 天

开发

# Desarrollo con watch mode
npm run dev

# Build
npm run build

# Lint
npm run lint

OpenTelemetry 日志结构

日志遵循 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 tools
get_field_valuesB

Get the most common values for a specific field. Useful for discovering available services, log levels, or other field values.

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
fieldYesThe field to get values for. Examples: 'service.name', 'level', 'host.name'
sizeNoMaximum 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.

NameRequiredDescriptionDefault
environmentYesEnvironment 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.

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
search_by_fieldC

Search logs by a specific field and value.

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
fieldYesThe field name to search. Examples: 'user_id', 'request_id', 'endpoint'
valueYesThe value to search for
timeRangeNoTime range to search within
sizeNoMaximum number of results to return (default: 50)
search_by_serviceC

Search logs filtered by service name, optionally with additional filters.

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
serviceNameYesThe service name to filter by
levelNoLog level to filter by
queryNoAdditional free-text query to apply
timeRangeNoTime range to search within
sizeNoMaximum 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.

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
traceIdYesThe OpenTelemetry trace ID to search for
sizeNoMaximum number of results to return (default: 100)
search_errorsC

Search for error logs, optionally filtered by service or additional query.

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
serviceNameNoOptional service name to filter by
queryNoAdditional free-text query to apply
timeRangeNoTime range to search within (default: 1h)
sizeNoMaximum 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'

NameRequiredDescriptionDefault
environmentYesEnvironment to search: 'dev'/'prod' (iOS) or 'android-dev'/'android-prod' (Android)
queryYesFree-text search query using Lucene syntax. Examples: 'error', 'status:500 AND service.name:auth'
timeRangeNoTime range to search within. Defaults to 1h if not specified.
sizeNoMaximum number of results to return (default: 50, max: 200)

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 8 tool updatesv1.0.0
    • First observedget_field_values
    • First observedget_mapping
    • First observedget_sample_log
    • First observedsearch_by_field
    • First observedsearch_by_service
    • First observedsearch_by_trace
    • First observedsearch_errors
    • First observedsearch_logs

TDQS

A3.5/5.0

Scored across 8 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessNo recent community issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables querying and searching logs from Kibana (ELK stack) via MCP, with support for project-based data views, trace ID correlation, and log expansion.
    -
  • A
    license
    A
    quality
    A
    maintenance
    Enables 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.
    3
    MIT