r7-log-search-mcp

A read-only MCP server for Rapid7 InsightIDR log discovery, LEQL search, analytics, and paginated results. Built with TypeScript and Bun.

Connect it to Codex or OpenCode to investigate your logs in natural language. Large results are paged automatically instead of being rejected at the 64 KB tool-output limit.

This is an independent community project, unaffiliated with Rapid7.

Requirements

• Bun 1.4 or later.

• A Rapid7 Platform API key with Log Search access to the logs you need. An ingestion token will not work.

• Your organization's region: us, us2, us3, eu, ca, au, or ap.

Related MCP server: rapid7-mcp

Install

git clone https://github.com/Ownistic/r7-log-search-mcp.git
cd r7-log-search-mcp
bun install --frozen-lockfile
cp .env.example .env
chmod 600 .env

Edit .env locally:

RAPID7_API_KEY=your-platform-api-key
RAPID7_REGION=eu

Use an API key with the minimum permissions required. Keep it in .env or your client's environment configuration; do not put it in prompts or commit it. .env is ignored by Git.

Run bun start to start the stdio server. It waits for an MCP client on stdin; it has no web interface or listening HTTP port. The source runs directly with Bun, so no build step is needed.

Connect Codex

Add this to ~/.codex/config.toml, replacing /absolute/path/r7-log-search-mcp with your checkout path:

[mcp_servers.rapid7]
command = "bun"
args = ["run", "--env-file=/absolute/path/r7-log-search-mcp/.env", "/absolute/path/r7-log-search-mcp/src/index.ts"]
tool_timeout_sec = 30

If Codex cannot find Bun, use its absolute executable path for command. Restart or reconnect the client after setup or source updates. Run codex mcp list to check registration. A copy of this configuration is in examples/codex.toml.

Connect OpenCode

Merge this into your OpenCode configuration, replacing the absolute paths:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "rapid7": {
      "type": "local",
      "command": [
        "bun",
        "run",
        "--env-file=/absolute/path/r7-log-search-mcp/.env",
        "/absolute/path/r7-log-search-mcp/src/index.ts"
      ],
      "enabled": true,
      "timeout": 30000
    }
  }
}

Run opencode mcp list to check registration. See examples/opencode.json.

Both clients can inject RAPID7_API_KEY and RAPID7_REGION instead of loading a file. For Codex, omit the env-file argument and use env_vars = ["RAPID7_API_KEY", "RAPID7_REGION"]. For OpenCode, use its MCP environment configuration.

Use it

Ask your agent, for example:

Find the production API logs and search the last 24 hours for errors involving merchant ABC123. Include timestamps and log IDs, and follow all result pages before drawing conclusions.

LEQL examples include where(error), where(error) calculate(count), and where(error) groupby(service) calculate(count). Field names depend on your logs. Searches default to the last 15 minutes; you can request relative windows or absolute Unix timestamps in milliseconds.

Pagination and limits

• Each tool payload is limited to 64,000 UTF-8 bytes. Larger query results are split into pages without dropping events. The agent follows rapid7_continue automatically when instructed to inspect all results.

• An individual oversized event or analytics object is delivered as JSON text fragments that can be joined and decoded. Other query results use ordinary event pages.

• pending means Rapid7 is still searching; more means another page is available. Only complete with no continuation marks the end of the search.

• Each call makes at most one Rapid7 request. Cached pages make none. There is no automatic retry or unbounded polling. Requests time out after 20 seconds; numeric retry delays are returned when available.

• Tokens live in memory for up to 30 minutes. Restarting the server, or eviction under the 200-token/8 MiB cache budget, invalidates older tokens. Repeat the original search if a token expires. Upstream query links can expire earlier.

• Individual upstream responses remain limited to 4 MiB. Local paging cannot reduce what Rapid7 sends. An upstream response over that limit requires a narrower query or time window.

• Catalog pages support a limit of 1–100. Catalog filters are local; lowering a catalog limit or filtering cannot reduce the upstream response size.

Security and privacy

The server exposes read-only discovery and search tools. It cannot change logs, rules, investigations, or account settings. It sends your API key only to your configured regional Rapid7 endpoint over HTTPS and rejects redirects and continuation links outside that endpoint.

Logs can contain secrets, personal information, and malicious instructions. Treat log content as evidence. Catalog ingestion credentials are omitted, and exact occurrences of the configured API key are redacted from returned data. General secret and personal-data redaction is not provided. Use appropriate key permissions and your MCP client's approval and data-sharing controls.

See SECURITY.md for vulnerability reporting.

Development

bun install --frozen-lockfile
bun run check
bun test
bun run format:check

Tests use synthetic data and a test-only fetch preload for the real Bun stdio subprocess. They do not require credentials or make live Rapid7 requests. CI runs the same checks. See CONTRIBUTING.md, CHANGELOG.md, and RELEASING.md.

License

MIT. Copyright © 2026 Ownistic.

References

• Rapid7 InsightIDR REST API

• Rapid7 Log Search API walkthrough

• MCP TypeScript SDK

• Codex MCP configuration

• OpenCode MCP configuration