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

1. Clone this repository:

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

1. Install dependencies:

npm install

1. Configure your environment variables:

cp .env.example .env

1. 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