MCP 服务器

rapid7-mcp-server

Enables querying Rapid7 InsightIDR logs using natural language through AI assistants, with support for time filtering, logset selection, and LEQL queries.

README

Rapid7 MCP Server

A Model Context Protocol (MCP) server that provides access to Rapid7 InsightIDR log querying capabilities through AI assistants.

Features

Query Rapid7 InsightIDR logs using natural language through AI assistants
Support for time-based log filtering with ISO8601 datetime format
Configurable pagination and logset targeting
Optional query filtering with LEQL (Log Entry Query Language)
Automatic datetime conversion from ISO8601 to UNIX timestamps
List available logsets and query by name
Poll running query status

Installation

Clone or download this repository
Install dependencies:
```
npm install
```

Testing (TLDR)

# Run all tests
npm test

Tests use mocked API calls - no real API keys needed.

Configuration

You'll need:

A valid Rapid7 InsightIDR API key
Access to the Rapid7 EU region (or modify the URL for other regions)
The logset ID you want to query (or use the listRapid7Logsets tool to discover them)

MCP Client Configuration

To use this server with MCP-compatible applications, you need to configure them with the server path and required environment variables.

Environment Variables

RAPID7_API_KEY: Your Rapid7 InsightIDR API key (required)
RAPID7_BASE_URL: The Rapid7 API base URL (optional, defaults to EU region)

Configuration Example

Add this configuration to your MCP config file:

{
  "mcpServers": {
    "rapid7": {
      "command": "node",
      "args": [
        "/path/to/your/rapid7-mcp-server/mcp-server.js"
      ],
      "env": {
        "RAPID7_API_KEY": "your-api-key-here",
        "RAPID7_BASE_URL": "https://eu.rest.logs.insight.rapid7.com"
      }
    }
  }
}

Regional Configuration

For different Rapid7 regions, update the RAPID7_BASE_URL:

EU: https://eu.rest.logs.insight.rapid7.com (default)
US: https://us.rest.logs.insight.rapid7.com
CA: https://ca.rest.logs.insight.rapid7.com
AU: https://au.rest.logs.insight.rapid7.com
AP: https://ap.rest.logs.insight.rapid7.com

Security Notes

Never commit your API key to version control
Store API keys securely using your system's credential management
Consider using environment variables or secure vaults for production deployments
Ensure your API key has appropriate permissions for log querying

Usage

Running the Server

node mcp-server.js

Using with MCP Inspector

For testing and development:

npm run inspector

Available Tools

1. queryRapid7Logset

Query Rapid7 logs with specified parameters for an entire log set using logset ID.

Parameters

from (string, required): Start datetime in ISO8601 format (e.g., "2024-01-15T10:00:00Z")
to (string, required): End datetime in ISO8601 format (e.g., "2024-01-15T11:00:00Z")
perPage (number, optional): Number of results per page (default: 100)
logsetId (string, required): The Rapid7 logset ID to query
query (string, optional): LEQL query string for filtering logs

Example Usage

{
  "from": "2024-01-15T10:00:00Z",
  "to": "2024-01-15T11:00:00Z",
  "perPage": 50,
  "logsetId": "your-logset-id",
  "query": "where(source_ip=192.168.1.1)"
}

2. queryRapid7LogsetByName

Query Rapid7 logs with specified parameters for a logset identified by name instead of ID.

Parameters

logsetName (string, required): Name of the logset to query
from (string, required): Start datetime in ISO8601 format (e.g., "2024-01-15T10:00:00Z")
to (string, required): End datetime in ISO8601 format (e.g., "2024-01-15T11:00:00Z")
perPage (number, optional): Number of results per page (default: 100)
query (string, optional): LEQL query string for filtering logs

Example Usage

{
  "logsetName": "Security Events",
  "from": "2024-01-15T10:00:00Z",
  "to": "2024-01-15T11:00:00Z",
  "perPage": 100,
  "query": "where(\"failed login\", loose)"
}

3. listRapid7Logsets

List all available Rapid7 log sets in your account. Useful for discovering logset names and IDs.

Parameters

None required.

Example Usage

{}

Response

Returns a list of all available logsets with their IDs, names, and descriptions.

4. pollRapid7Query

Poll the status of a running Rapid7 log query using its query ID. Useful for long-running queries.

Parameters

queryId (string, required): The unique ID of the query to poll (as returned by query tools)
timeRange (string, optional): Time range (e.g., 'last 1 day', 'last 7 days'). Defaults to 'last 1 day'

Example Usage

{
  "queryId": "query-12345-abcdef",
  "timeRange": "last 7 days"
}

Common Response Format

All tools return JSON-formatted data from Rapid7 InsightIDR, including:

Log entries matching your criteria
Metadata about the query execution
Pagination information if applicable
Query status for polling operations

Error Handling

The server includes comprehensive error handling for:

Invalid datetime formats
API authentication failures
Network connectivity issues
Malformed responses
Empty or invalid parameters
Missing environment variables

API Endpoints

This server connects to the Rapid7 EU REST API:

Base URL: https://eu.rest.logs.insight.rapid7.com
Query logset by ID: /query/logsets/{logsetId}
Query logset by name: /query/logsets
List logsets: /management/logsets
Poll query: /query/{queryId}

To use a different region, modify the URL in mcp-server.js.

Development

Project Structure

rapid7-mcp-server/
├── mcp-server.js     # Main server implementation
├── package.json      # Dependencies and scripts
└── README.md         # This file

Dependencies

@modelcontextprotocol/sdk: MCP SDK for server implementation
node-fetch: HTTP client for API requests
zod: Schema validation for tool parameters

License

MIT License

This project is licensed under the MIT License, one of the most permissive open source licenses available. You are free to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of this software.