de en es ja ko ru zh

OpenSearch Logs MCP Server

Name: OpenSearch Logs MCP Server
Author: luis-dominguez-stori

by luis-dominguez-stori

Overview Schema Source Related Servers Discussions Admin

TypeScript

Remote

OpenSearch Logs MCP Server

OpenSearch에서 OpenTelemetry 로그를 쿼리하기 위한 MCP(Model Context Protocol) 서버입니다. 개발(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)

예시:

"지난 1시간 동안 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 환경에서 지난 1시간 동안의 오류 검색"
"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 구문을 지원합니다:

구문	설명	예시
`용어`	모든 필드에서 검색	`error`
`필드:값`	특정 필드에서 검색	`event:kyc_error`
`필드:값`	와일드카드	`errorMessage:timeout`
`AND`	두 용어 모두 포함	`error AND authentication`
`OR`	용어 중 하나라도 포함	`error OR warning`
`NOT`	용어 제외	`NOT debug`
`[a TO b]`	범위	`statusCode:[400 TO 499]`
`"정확한 문구"`	정확히 일치	`"connection refused"`

시간 범위

값	설명
`15m`	최근 15분
`1h`	최근 1시간 (기본값)
`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.

Name	Required	Description
`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
`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
`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
`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
`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
`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 updatesv1.0.0Apr 20, 2026
- 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

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.5/5.0

Scored 2026-04-20 18:40 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

Resources

Related MCP Connectors

LogsLoomA
io.github.efim23
Ingest and search LogsLoom logs from coding agents.
Observability Monitoring Developer Tools
41
https://mcp.logsloom.com/mcp
Auralogs
ai.auralogs
Read-only access to Auralogs production logs: search logs, inspect errors, review AI analyses.
Observability Monitoring
2
https://mcp.auralogs.ai/mcp
Superlog
sh.superlog
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Monitoring Observability
21,039
https://api.superlog.sh/mcp
LogBrewA
co.logbrew
Read LogBrew errors, slow traces, logs, and product analytics, and triage issues with consent.
Monitoring Observability
23
https://logbrew.co/mcp

Related MCP Servers

cloudwatch-mcp
Monitoring Observability Cloud Platforms
nikhilchintawar
A
license
A
quality
D
maintenance
Enables searching and analyzing AWS CloudWatch logs with support for configurable log groups, time-based searches, and service-specific log stream filtering.
Updated 9 months ago (2026-02-20 15:54 UTC)
5
MIT
datadog-logs-mcp
Monitoring Observability
bgrgndzz
A
license
A
quality
D
maintenance
Enables querying and analyzing Datadog logs through search, aggregation, and index listing.
Updated 8 months ago (2026-03-08 23:33 UTC)
3
13 npm
MIT
ELK Log Query MCP
Observability Monitoring
zhengziha
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.
Updated 2 months ago (2026-09-15 06:25 UTC)
-
ccv2-logs-mcp
bfernandez2-seidor
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.
Updated 3 months ago (2026-07-27 06:38 UTC)
3
MIT

OpenSearch Logs MCP Server

아키텍처

적용된 원칙

설치

Cursor 설정

사용 가능한 도구

search_logs

search_by_trace

search_by_service

search_errors

get_field_values

search_by_field

get_mapping

get_sample_log

Lucene 검색 구문

시간 범위

개발

OpenTelemetry 로그 구조

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

cloudwatch-mcp

datadog-logs-mcp

ELK Log Query MCP

ccv2-logs-mcp

`search_logs`

`search_by_trace`

`search_by_service`

`search_errors`

`get_field_values`

`search_by_field`

`get_mapping`

`get_sample_log`