OpenSearch Logs MCP Server
OpenSearch Logs MCP Server
OpenSearch内のOpenTelemetryログをクエリするためのMCP (Model Context Protocol) サーバーです。開発環境 (dev) および本番環境 (prod) をサポートしています。
アーキテクチャ
このサーバーはSOLID原則とクリーンアーキテクチャに従っています:
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): サービスは抽象(インターフェース)に依存する
ビルダーパターン: クエリを流れるように構築するための
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環境で過去1時間の'error'を含むログを検索"
"prod環境で過去6時間のステータス500のログを検索"
search_by_trace
OpenTelemetryのトレースに関連するすべてのログを検索します。
パラメータ | 型 | 必須 | 説明 | |
environment |
|
| ✅ | クエリ対象の環境 |
traceId | string | ✅ | トレースID | |
size | number | ❌ | 最大結果数 (デフォルト: 100) |
例:
"dev環境のトレース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環境の過去1時間のエラーを表示"
"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分 |
| 過去1時間 (デフォルト) |
| 過去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