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
.envfile 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 texttimeRange: Time range (e.g., 1h, 24h, 7d)maxResults: Maximum number of results to returnindex: Index pattern to search
2. Get Alert Details
Get detailed information about a specific alert by ID.
Parameters:
id: The alert IDindex: 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 alertsindex: 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