OpenSearch MCP Server

A Model Context Protocol (MCP) server for querying and analyzing Wazuh security logs stored in OpenSearch.

Features

Search for security alerts with advanced filtering
Get detailed information about specific alerts
Generate statistics on security events
Visualize alert trends over time
Progress reporting for long-running operations
Structured error handling

Prerequisites

Node.js v16 or higher
Access to an OpenSearch instance containing Wazuh security logs

Installation

Option 1: Use with npx directly from GitHub (recommended)

You can run this tool directly using npx without cloning the repository:

# Run the latest version from GitHub
npx github:jetbalsa/mcp-opensearch-js

# Run with debug mode enabled
npx github:jetbalsa/mcp-opensearch-js --debug

# You can also specify a specific branch or commit
npx github:jetbalsa/mcp-opensearch-js#main

Option 2: Local Installation

Clone this repository:

git clone https://github.com/jetbalsa/mcp-opensearch-js.git
cd mcp-opensearch-js

Install dependencies:

npm install

Configure your environment variables:

cp .env.example .env

Edit the .env file with your OpenSearch connection details:

OPENSEARCH_URL=https://your-opensearch-endpoint:9200
OPENSEARCH_USERNAME=your-username
OPENSEARCH_PASSWORD=your-password
DEBUG=false

Running the Server

Start the server:

npm start

This will start the server in stdio mode.

Enable debug logging:

npm run stdio:debug

Test with MCP CLI:

npm run dev

This runs the server with the FastMCP CLI tool for interactive testing.

Test with MCP Inspector:

npm run inspect

This starts the server and connects it to the MCP Inspector for visual debugging.

Server Tools

The server provides the following tools:

1. Search Alerts

Search for security alerts in Wazuh data.

Parameters:

query: The search query text
timeRange: Time range (e.g., 1h, 24h, 7d)
maxResults: Maximum number of results to return
index: Index pattern to search

2. Get Alert Details

Get detailed information about a specific alert by ID.

Parameters:

id: The alert ID
index: Index pattern

3. Alert Statistics

Get statistics about security alerts.

Parameters:

timeRange: Time range (e.g., 1h, 24h, 7d)
field: Field to aggregate by (e.g., rule.level, agent.name)
index: Index pattern

4. Visualize Alert Trend

Visualize alert trends over time.

Parameters:

timeRange: Time range (e.g., 1h, 24h, 7d)
interval: Time interval for grouping (e.g., 1h, 1d)
query: Query to filter alerts
index: Index pattern

Example Usage

Using the MCP CLI tool:

> tools
Available tools:
- searchAlerts: Search for security alerts in Wazuh data
- getAlertDetails: Get detailed information about a specific alert by ID
- alertStatistics: Get statistics about security alerts
- visualizeAlertTrend: Visualize alert trends over time

> tools.searchAlerts(query: "rule.level:>10", timeRange: "12h", maxResults: 5)

Using with a Client

To use this MCP server with a client implementation:

import { Client } from "@modelcontextprotocol/sdk";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const client = new Client(
  {
    name: "example-client",
    version: "1.0.0",
  },
  {
    capabilities: {},
  },
);

const transport = new SSEClientTransport(new URL(`http://localhost:3000/sse`));

await client.connect(transport);

// Use tools
const result = await client.executeTool("searchAlerts", {
  query: "rule.level:>10",
  timeRange: "24h",
  maxResults: 10
});

console.log(result);

License

MIT

OpenSearch MCP Server

Integrations