io.github.rijul170/alertlogic-mcp
MCP server for Alert Logic MDR — incident response, log search, SOAR, and SOC workflows
Open source Open in the app JSON README (API)
About
MCP server for Alert Logic MDR — incident response, log search, SOAR, and SOC workflows
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- rijul170
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-07-26T18:58:13Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:18
- Updated
- 2026-08-29 04:01:18
- Origin id
io.github.rijul170/alertlogic-mcp
README
<!-- mcp-name: io.github.rijul170/alertlogic-mcp -->
<div align="center">
# Alert Logic MCP Server
**Bring the full Alert Logic MDR platform into your AI assistant.**
[](https://github.com/rijul170/alertlogic-mcp/actions/workflows/test.yml)
[](https://pypi.org/project/alertlogic-mcp/)
[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.rijul170/alertlogic-mcp)
A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the complete Alert Logic API surface as structured tools any MCP-compatible client (Claude Desktop, Claude Code, Cursor, …) can call directly — enabling AI-powered security operations, incident response, and threat hunting at MSSP scale.
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](#module-overview)
[](#license)
[](https://github.com/rijul170/alertlogic-mcp)
</div>
> **For incident responders:** Query Alert Logic MDR incidents, elaborate raw log evidence, kick off SOAR playbooks, and search logs with SQL — all through Claude. Designed for MSSP-scale multi-account operations.
---
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Architecture](#architecture)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Claude Code Integration](#claude-code-integration-http-mode)
- [Claude Desktop Integration](#claude-desktop-integration-stdio-mode)
- [Module Overview](#module-overview)
- [SOC Quick Start](#soc-quick-start)
- [Built-in SOC Playbooks](#built-in-soc-playbooks)
- [Multi-Account MSSP Usage](#multi-account-mssp-usage)
- [Security Notes](#security-notes)
- [Testing](#testing)
- [Troubleshooting](#troubleshooting)
- [Contributing](#contributing)
- [License](#license)
---
## Overview
This MCP server wraps the Alert Logic MDR platform API and exposes it as 473+ structured tools that any MCP-compatible AI client can call directly. It covers the full Alert Logic API surface — incident response, SQL-based log search, SOAR playbook automation, asset management, vulnerability analysis, user and credential management, billing, and more — organized into 46 domain modules. Auth, retries, pagination, token management, and JSON shaping are handled server-side; your AI client simply calls the tool by name.
---
## Features
- **Incident Response** — List, get, elaborate (raw log evidence), complete, reopen, add notes, and add feedback to incidents. Friendly-ID lookup included.
- **SQL Log Search** — Submit Alert Logic log search queries in SQL, poll status, retrieve results, and release sessions.
- **SOAR Playbook Automation** — List, get, execute, and monitor SOAR playbooks; manage inquiries, triggers, and execution state.
- **Asset Topology** — Query the full asset inventory, declare and remove assets, set properties, and retrieve topology graphs for any deployment.
- **Vulnerability Management** — List exposures by severity, retrieve per-asset vulnerabilities, search the vulnerability knowledge base, and manage remediation items.
- **User & Access Key Management** — Full CRUD on users, roles, access keys, MFA settings, and password resets across accounts.
- **Multi-Account MSSP Support** — Per-tool `account_id` override and bulk cross-account operations (bulk deployments, bulk health checks, partner incidents).
- **Built-in SOC Playbooks** — Six tools that surface pre-written IR guides, threat-hunt workflows, MITRE ATT&CK mappings, and tool reference guides directly in-context.
- **Tickets & Watchlist** — Create, update, and close tickets; manage the alerting watchlist.
- **Cloud & Azure Explorer** — Browse cloud resource topology across AWS and Azure environments.
- **Analytics Engine** — Access AE content, rules, analytics, tags, tuning, and publication across multiple AE subsystems.
- **Infrastructure Operations** — Manage environments, scan schedules, scan results, network controls, ingest sources, and log integrations.
---
## Architecture
```
+--------------------+ stdio / streamable-HTTP (MCP) +--------------------------------+
| MCP Client | <-------------------------------------> | AlertLogic MCP Server |
| (Claude Desktop, | | (this repo, main.py) |
| Claude Code, …) | | |
+--------------------+ | 46 modules (~473 tools): |
| incidents, soc, soar, |
| assets, vuln, users, … |
| | |
| base.py (HTTP, AIMS auth, |
| token cache, retries) |
+----------+---------------------+
|
v HTTPS + AIMS Bearer token
+-----------------------------+
| AlertLogic MDR Platform |
| api.cloudinsight....com |
+-----------------------------+
```
**Transport**: The server supports three MCP transports selectable via `MCP_TRANSPORT`:
- `stdio` (default) — launched on demand by your MCP client; no network port opened.
- `streamable-http` — persistent HTTP server; suitable for Claude Code and remote clients.
- `sse` — Server-Sent Events transport for SSE-capable clients.
**Authentication**: Alert Logic uses AIMS Bearer token auth. The server exchanges your `access_key_id:secret_key` API key for a short-lived Bearer token on first use, caches it, and re-authenticates automatically when the token expires — no manual token rotation required.
**`base.py`** centralizes HTTP method helpers (`_get`, `_post`, `_put`, `_delete`), per-service URL routing (Account-Topology service, global service, `_at`-prefixed routes), error translation, and the AIMS token cache.
---
## Prerequisites
- Python 3.10 or newer
- `uv` (recommended) or `pip`
- An Alert Logic account with API access enabled
- An Alert Logic API key (access key ID + secret key; see [Configuration](#configuration))
---
## Installation
```bash
# 1. Clone the repository
git clone https://github.com/rijul170/alertlogic-mcp.git
cd alertlogic-mcp
# 2. Create a virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -r requirements.txt
# Or with uv (faster):
uv venv
uv pip install -r requirements.txt
# 3. Configure credentials
cp .env.example .env
$EDITOR .env # fill in the required variables (see below)
```
---
## Configuration
All configuration is via environment variables, loaded from `.env` at startup.
### Required variables
| Variable | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `ALERTLOGIC_API_KEY` | API key in `access_key_id:secret_key` format (see below for how to create one) |
| `ALERTLOGIC_BASE_URL` | API base URL — `https://api.cloudinsight.alertlogic.com` (US) or `https://api.cloudinsight.alertlogic.co.uk` (UK) |
| `ALERTLOGIC_ACCOUNT_ID` | Your Alert Logic account ID (visible in the console URL and account settings) |
### Optional variables
| Variable | Default | Description |
| ------------------------- | -------------- | -------------------------------------------------------- |
| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `sse`, or `streamable-http` |
| `MCP_HOST` | `127.0.0.1` | Bind host (HTTP transports only) |
| `MCP_PORT` | `8000` | Bind port (HTTP transports only) |
| `ALERTLOGIC_MCP_READONLY` | _(off)_ | Set to `true` to register only read tools — write and destructive tools are never exposed to the AI client |
| `ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE` | _(off)_ | Destructive tools (deletes, SOAR playbook execution, scan launches, ...) are suppressed by default. Set to `true` to arm all of them, or a comma-separated list of tool names to arm selectively |
### Optional service URL overrides
These default to Alert Logic's standard endpoints. Override only if you have a custom deployment:
```dotenv
ALERTLOGIC_GLOBAL_BASE_URL=https://api.global-services.global.alertlogic.com
ALERTLOGIC_AETUNER_BASE_URL=https://aetuner.mdr.global.alertlogic.com
ALERTLOGIC_CONNECTORS_BASE_URL=https://connectors.mdr.global.alertlogic.com
ALERTLOGIC_RESPONDER_BASE_URL=https://api.responder.alertlogic.com
```
### Creating an API key
1. Sign in to the Alert Logic console.
2. Navigate to **Manage → Users**, select your user, then open **Access Keys → Create**.
3. Copy the **Access Key ID** and **Secret Key**.
4. Combine them as `access_key_id:secret_key` (with the colon) and set that as `ALERTLOGIC_API_KEY`.
---
## Claude Code Integration (HTTP mode)
Start the server in HTTP mode:
```bash
MCP_TRANSPORT=streamable-http python main.py
```
Then register it in your Claude Code project or user MCP config (`.claude/settings.json` or `~/.claude/settings.json`):
```json
{
"mcpServers": {
"alertlogic-mcp": {
"type": "http",
"url": "http://localhost:8000/mcp"
}
}
}
```
Or via the CLI:
```bash
claude mcp add --transport http alertlogic-mcp http://localhost:8000/mcp
```
---
## Claude Desktop Integration (stdio mode)
Edit `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%AppData%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"alertlogic-mcp": {
"command": "/absolute/path/to/.venv/bin/python",
"args": ["/absolute/path/to/alertlogic-mcp/main.py"]
}
}
}
```
> Use absolute paths. Tilde (`~`) is not expanded by Claude Desktop. Point `command` at the venv Python, not the system Python.
Restart Claude Desktop. Alert Logic tools will appear in the tool picker.
---
## Module Overview
46 modules, ~473 tools, organized by domain:
### Incident Response
| Module | Tools | Key operations |
| ---------------- | :---: | --------------------------------------------------------------------------------------- |
| `incidents_mcp` | 11 | List, get, friendly-ID lookup, complete, reopen, add notes, add feedback, list partner incidents |
| `soc` | 14 | Submit/poll/release SQL log searches, list exposures, get health summary |
| `soc_playbooks` | 6 | Built-in IR guide, threat-hunt workflow, MITRE mapping, tool guides (see below) |
### Asset Management
| Module | Tools | Key operations |
| ---------------- | :---: | --------------------------------------------------------------------------------------- |
| `assets` | 15 | Query assets, get topology, declare/batch-declare/remove assets, set properties |
| `assets_manager` | 5 | Higher-level asset management and grouping |
| `cloud_explorer` | 12 | Browse AWS cloud resource topology by deployment |
| `azure_explorer` | 13 | Browse Azure resource topology by deployment |
### SOAR
| Module | Tools | Key operations |
| ------ | :---: | ------------------------------------------------------------------------------------------------- |
| `soar` | 33 | List/get playbooks and actions, create/get/query executions, manage inquiries and triggers |
### Vulnerabilities & Compliance
| Module | Tools | Key operations |
| -------------------- | :---: | --------------------------------------------------------------------- |
| `vulnerability` | 10 | List exposures by severity, get per-asset exposures |
| `vulnerabilities_kb` | 9 | Query the vulnerability knowledge base (CVE details, CVSS, remediation) |
| `compliance` | 4 | List remediation items, conclude/dispose/undispose remediations |
### Users & Authentication
| Module | Tools | Key operations |
| ------------- | :---: | ------------------------------------------------------------------------------------- |
| `users` | 30 | Full CRUD on users, roles, access keys, MFA, and password resets |
| `auth` | 6 | AIMS token management, list managed accounts, account ID enumeration |
| `credentials` | 10 | IAM role and Azure AD credential CRUD, scan credentials, decrypted retrieval |
| `themis` | 3 | Credential validation and verification |
### Infrastructure & Deployments
| Module | Tools | Key operations |
| ------------------ | :---: | --------------------------------------------------------------------------- |
| `deployments` | 5 | List, get, create, update, delete deployments |
| `environments` | 10 | Manage Alert Logic environments and environment configuration |
| `network_controls` | 15 | Exclusion CRUD, asset checks, tag/host whitelist management |
| `scan_scheduler` | 13 | Create, update, and manage scan schedules per deployment |
| `scan_result` | 4 | Retrieve and analyze scan results |
### Analytics Engine
| Module | Tools | Key operations |
| ----------- | :---: | --------------------------------------------------------------------------- |
| `aecontent` | 11 | Manage AE content (detection content library) |
| `aefr` | 23 | AE flat-rule management |
| `aerta` | 13 | AE real-time analytics management |
| `aetag` | 23 | AE tag and correlation rule management |
| `aepublish` | 1 | Publish AE analytics updates |
| `aemanual` | 2 | Manual AE analytics operations |
| `kalm` | 5 | AE knowledge and analytics lifecycle management |
### Ticketing & Watchlist
| Module | Tools | Key operations |
| ------------------ | :---: | ------------------------------------------------------- |
| `tickets` | 8 | Create, get, update, list, and close tickets |
| `watchlist_module` | 7 | Manage the alerting watchlist (add, remove, query items) |
### Operations & Platform
| Module | Tools | Key operations |
| --------------------- | :---: | ---------------------------------------------------------------------- |
| `account_management` | 7 | Account details, lookup by name, parent/child relationships, topology |
| `policies` | 2 | List and inspect policies |
| `billing` | 12 | List and inspect subscriptions, entitlements, and billing data |
| `common` | 22 | Herald notifications, subscriptions, webhook/email connectors, endpoints |
| `ingest_module` | 6 | Manage log ingest sources and ingest configuration |
| `logging_integration` | 17 | Log source CRUD, source types, collection management |
| `otis` | 7 | On-demand threat intelligence search |
| `notify` | 2 | Notification dispatch |
| `search_stylist` | 2 | Log search query formatting and suggestion |
| `informant` | 2 | Informant service queries |
| `strawboss` | 10 | Strawboss job and schedule management |
| `tacoma` | 12 | Tacoma service operations |
| `album` | 10 | Evidence and artifact management |
| `usage_module` | 4 | Account usage statistics and reporting |
| `bulk_ops` | 2 | Cross-account bulk operations (bulk deployments, bulk health checks) |
| `suggestions` | 10 | AI-assisted search and investigation suggestions |
| `seceng` | — | Security Engineering: Cargo schedules/executions, AETuner analytics/tuning |
---
## SOC Quick Start
Once connected, try these prompts in Claude:
```
Show me all open critical incidents from the last 24 hours
```
```
Get the elaborations (raw log evidence) for incident INC-12345
```
```
Search logs for SSH login failures from 10.0.0.5 in the last hour using SQL
```
```
Add a note to incident INC-12345: Confirmed malicious, escalating to customer
```
```
List all deployments and their health status across all accounts
```
```
Show me the top 10 critical vulnerabilities for host web-prod-01
```
```
Run the SOC IR playbook to walk me through incident response steps
```
---
## Built-in SOC Playbooks
The `soc_playbooks` module provides six tools that surface curated, in-context operational guides — no external documentation lookups required:
| Tool | Contents |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `soc_ir_start` | End-to-end incident response workflow: triage checklist, scoping steps, containment criteria, evidence collection, and documentation requirements |
| `soc_threat_hunt` | Hypothesis-driven threat-hunting playbook: IOC-based hunts, TTP-based hunts, and log query templates for common attack patterns |
| `soc_mitre_attack_guide` | MITRE ATT&CK tactic/technique reference mapped to Alert Logic detection types and recommended search queries |
| `soc_alertlogic_tool_guide` | Quick reference for Alert Logic MCP tools organized by investigation task (triage, scoping, evidence, containment) |
| `soc_log_query_templates` | Ready-to-run SQL log query templates for common SOC scenarios: auth failures, lateral movement, C2 beaconing, data exfiltration, and more |
| `soc_summary` | Executive-ready incident summary template and field-population guidance |
These tools are designed to be called at the start of an investigation to load relevant context before querying live data.
---
## Multi-Account MSSP Usage
The server is designed for MSSP environments where a single API key manages multiple child accounts:
**Partner incident listing** — `incidents_list_partner` returns incidents across all managed accounts in a single call, with account ownership labels.
**Per-tool account override** — Most tools accept an optional `account_id` parameter. Pass a child account's ID to scope any query to that account without changing your `.env` configuration:
```
Get all open incidents for account <child-account-id>
```
**Bulk operations** — `bulk_list_deployments` fans out a deployments query across all managed accounts and returns aggregated results. `bulk_health_check` does the same for health status.
**Account topology** — `aims_get_account_topology` and `aims_list_accounts_by_relationship` map the parent/child account hierarchy, useful for scoping operations before running them.
> **Tenant isolation**: When working across multiple accounts, always confirm the target account before running write operations (containment, note-adding, ticket creation). The server does not enforce cross-tenant guards beyond what the Alert Logic API provides.
---
## Security Notes
- **Read-only mode**: Set `ALERTLOGIC_MCP_READONLY=true` to register only read tools at startup. Write and destructive tools are never exposed to the AI client, regardless of what is asked.
- **Destructive operation gating**: Even with writes enabled, destructive tools (user/asset deletes, SOAR playbook execution, scan launches, key revocation, ...) are suppressed by default. Arm them explicitly via `ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE` — the recommended approach is a comma-separated list of specific tool names rather than `true`:
```bash
# Enable only incident completion workflow deletes
ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE=user_delete,playbook_execute
```
- Every tool carries MCP `readOnlyHint`/`destructiveHint` annotations so compliant clients can apply their own confirmation policies.
- **Never commit `.env`.** It is excluded by `.gitignore`; only `.env.example` (with placeholders) is tracked.
- Treat `ALERTLOGIC_API_KEY` like a password. Rotate it immediately if you suspect exposure (chat logs, screen shares, lost device).
- **AIMS token handling**: The server exchanges your API key for a short-lived Bearer token on first use and caches it in memory. The token is refreshed automatically on expiry. The raw `secret_key` is not logged or transmitted after the initial AIMS authentication call.
- In `stdio` mode, the server opens no network port. In `streamable-http` or `sse` mode, bind to `127.0.0.1` (the default) unless you specifically need remote access, in which case add appropriate network controls.
- `base.py` does not log request bodies, response bodies, or credential material. If you fork and add logging, take care to exclude token and secret values.
- This repository ships no credentials of any kind.
---
## Testing
A standalone smoke-test script exercises a representative cross-section of tools without going through an MCP client:
```bash
python smoke_test.py
```
This verifies credential validity, network reachability, and base configuration before wiring the server into your MCP client.
---
## Troubleshooting
<details>
<summary><b>"Authentication failed" / 401 errors</b></summary>
- Confirm `ALERTLOGIC_API_KEY` is the full `access_key_id:secret_key` string, including the colon separator.
- Verify `ALERTLOGIC_BASE_URL` matches your datacenter (US `api.cloudinsight.alertlogic.com` vs. UK `api.cloudinsight.alertlogic.co.uk`).
- Check that the access key is still active in the Alert Logic console (Manage → Users → Access Keys).
- Confirm `ALERTLOGIC_ACCOUNT_ID` is correct — a mismatch can cause 401s on account-scoped endpoints.
</details>
<details>
<summary><b>Tools don't appear in Claude Desktop</b></summary>
- Use absolute paths in `claude_desktop_config.json`. Tilde (`~`) and relative paths are not expanded.
- Point `command` at the virtual environment's Python (`.venv/bin/python`), not the system Python.
- Check Claude Desktop logs for stderr output from this server: macOS logs are in `~/Library/Logs/Claude/`.
- Restart Claude Desktop fully (quit and reopen) after editing the config file.
</details>
<details>
<summary><b>"ModuleNotFoundError: mcp" or missing dependencies</b></summary>
You are running `python main.py` outside the virtual environment. Either activate it first (`source .venv/bin/activate`) or invoke the venv's Python directly (`/path/to/.venv/bin/python main.py`).
</details>
<details>
<summary><b>HTTP mode: connection refused on port 8000</b></summary>
Make sure you started the server with `MCP_TRANSPORT=streamable-http python main.py` before attempting to connect. The server only binds a port when a non-stdio transport is selected.
</details>
<details>
<summary><b>Empty results or silent failures</b></summary>
If all tool calls return empty results or fail silently, this is often caused by an SSO or proxy layer blocking outbound API calls. Try running from a non-proxied network or a different client to confirm. Also check that `ALERTLOGIC_BASE_URL` and `ALERTLOGIC_ACCOUNT_ID` are both correct for your environment.
</details>
---
## Contributing
PRs and issues are welcome.
1. Fork the repository, create a feature branch, commit your changes, and open a PR.
2. Add new Alert Logic endpoints as additional `@server.tool` definitions in the matching module file under `modules/`.
3. For a new module: create `modules/<name>.py` with a `setup(server)` function, then add it to the `MODULES` list in `main.py`.
4. Keep tool docstrings accurate and descriptive — the docstring is what the LLM sees when deciding whether and how to call the tool.
5. Run `python smoke_test.py` before submitting to verify basic functionality.
---
## Related MCP Servers
These three servers cover complementary layers of a security stack — network/log (Alert Logic), endpoint protection (Sophos), and EDR/threat intel (CrowdStrike). Use them together for full-stack AI-powered SOC operations.
| Server | Platform | Highlights |
|--------|----------|------------|
| [falcon-mcp](https://github.com/rijul170/falcon-mcp) | CrowdStrike Falcon | EDR telemetry, RTR, threat intel, MSSP Flight Control, 1,296 tools |
| [sophos-central-mcp](https://github.com/rijul170/sophos-central-mcp) | Sophos Central | Endpoint isolation, Live Discover SQL, XDR, email/firewall/DNS, 334 tools |
| [alertlogic-mcp](https://github.com/rijul170/alertlogic-mcp) | Alert Logic MDR | Incident response, SQL log search, SOAR, vulnerability management, 473 tools |
## License
MIT License. See [LICENSE](LICENSE) for full text.