{
"markdown": "\n\n\n\n# Alert Logic MCP Server\n\n**Bring the full Alert Logic MDR platform into your AI assistant.**\n\n[](https://github.com/rijul170/alertlogic-mcp/actions/workflows/test.yml)\n[](https://pypi.org/project/alertlogic-mcp/)\n[](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.rijul170/alertlogic-mcp)\n\nA [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.\n\n[](https://www.python.org/)\n[](https://modelcontextprotocol.io)\n[](#module-overview)\n[](#license)\n[](https://github.com/rijul170/alertlogic-mcp)\n\n
\n\n> **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.\n\n---\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Features](#features)\n- [Architecture](#architecture)\n- [Prerequisites](#prerequisites)\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Claude Code Integration](#claude-code-integration-http-mode)\n- [Claude Desktop Integration](#claude-desktop-integration-stdio-mode)\n- [Module Overview](#module-overview)\n- [SOC Quick Start](#soc-quick-start)\n- [Built-in SOC Playbooks](#built-in-soc-playbooks)\n- [Multi-Account MSSP Usage](#multi-account-mssp-usage)\n- [Security Notes](#security-notes)\n- [Testing](#testing)\n- [Troubleshooting](#troubleshooting)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## Overview\n\nThis 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.\n\n---\n\n## Features\n\n- **Incident Response** — List, get, elaborate (raw log evidence), complete, reopen, add notes, and add feedback to incidents. Friendly-ID lookup included.\n- **SQL Log Search** — Submit Alert Logic log search queries in SQL, poll status, retrieve results, and release sessions.\n- **SOAR Playbook Automation** — List, get, execute, and monitor SOAR playbooks; manage inquiries, triggers, and execution state.\n- **Asset Topology** — Query the full asset inventory, declare and remove assets, set properties, and retrieve topology graphs for any deployment.\n- **Vulnerability Management** — List exposures by severity, retrieve per-asset vulnerabilities, search the vulnerability knowledge base, and manage remediation items.\n- **User & Access Key Management** — Full CRUD on users, roles, access keys, MFA settings, and password resets across accounts.\n- **Multi-Account MSSP Support** — Per-tool `account_id` override and bulk cross-account operations (bulk deployments, bulk health checks, partner incidents).\n- **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.\n- **Tickets & Watchlist** — Create, update, and close tickets; manage the alerting watchlist.\n- **Cloud & Azure Explorer** — Browse cloud resource topology across AWS and Azure environments.\n- **Analytics Engine** — Access AE content, rules, analytics, tags, tuning, and publication across multiple AE subsystems.\n- **Infrastructure Operations** — Manage environments, scan schedules, scan results, network controls, ingest sources, and log integrations.\n\n---\n\n## Architecture\n\n```\n+--------------------+ stdio / streamable-HTTP (MCP) +--------------------------------+\n| MCP Client | <-------------------------------------> | AlertLogic MCP Server |\n| (Claude Desktop, | | (this repo, main.py) |\n| Claude Code, …) | | |\n+--------------------+ | 46 modules (~473 tools): |\n | incidents, soc, soar, |\n | assets, vuln, users, … |\n | | |\n | base.py (HTTP, AIMS auth, |\n | token cache, retries) |\n +----------+---------------------+\n |\n v HTTPS + AIMS Bearer token\n +-----------------------------+\n | AlertLogic MDR Platform |\n | api.cloudinsight....com |\n +-----------------------------+\n```\n\n**Transport**: The server supports three MCP transports selectable via `MCP_TRANSPORT`:\n- `stdio` (default) — launched on demand by your MCP client; no network port opened.\n- `streamable-http` — persistent HTTP server; suitable for Claude Code and remote clients.\n- `sse` — Server-Sent Events transport for SSE-capable clients.\n\n**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.\n\n**`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.\n\n---\n\n## Prerequisites\n\n- Python 3.10 or newer\n- `uv` (recommended) or `pip`\n- An Alert Logic account with API access enabled\n- An Alert Logic API key (access key ID + secret key; see [Configuration](#configuration))\n\n---\n\n## Installation\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/rijul170/alertlogic-mcp.git\ncd alertlogic-mcp\n\n# 2. Create a virtual environment and install dependencies\npython -m venv .venv\nsource .venv/bin/activate # Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\n\n# Or with uv (faster):\nuv venv\nuv pip install -r requirements.txt\n\n# 3. Configure credentials\ncp .env.example .env\n$EDITOR .env # fill in the required variables (see below)\n```\n\n---\n\n## Configuration\n\nAll configuration is via environment variables, loaded from `.env` at startup.\n\n### Required variables\n\n| Variable | Description |\n| ------------------------- | ----------------------------------------------------------------------------------------------- |\n| `ALERTLOGIC_API_KEY` | API key in `access_key_id:secret_key` format (see below for how to create one) |\n| `ALERTLOGIC_BASE_URL` | API base URL — `https://api.cloudinsight.alertlogic.com` (US) or `https://api.cloudinsight.alertlogic.co.uk` (UK) |\n| `ALERTLOGIC_ACCOUNT_ID` | Your Alert Logic account ID (visible in the console URL and account settings) |\n\n### Optional variables\n\n| Variable | Default | Description |\n| ------------------------- | -------------- | -------------------------------------------------------- |\n| `MCP_TRANSPORT` | `stdio` | Transport: `stdio`, `sse`, or `streamable-http` |\n| `MCP_HOST` | `127.0.0.1` | Bind host (HTTP transports only) |\n| `MCP_PORT` | `8000` | Bind port (HTTP transports only) |\n| `ALERTLOGIC_MCP_READONLY` | _(off)_ | Set to `true` to register only read tools — write and destructive tools are never exposed to the AI client |\n| `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 |\n\n### Optional service URL overrides\n\nThese default to Alert Logic's standard endpoints. Override only if you have a custom deployment:\n\n```dotenv\nALERTLOGIC_GLOBAL_BASE_URL=https://api.global-services.global.alertlogic.com\nALERTLOGIC_AETUNER_BASE_URL=https://aetuner.mdr.global.alertlogic.com\nALERTLOGIC_CONNECTORS_BASE_URL=https://connectors.mdr.global.alertlogic.com\nALERTLOGIC_RESPONDER_BASE_URL=https://api.responder.alertlogic.com\n```\n\n### Creating an API key\n\n1. Sign in to the Alert Logic console.\n2. Navigate to **Manage → Users**, select your user, then open **Access Keys → Create**.\n3. Copy the **Access Key ID** and **Secret Key**.\n4. Combine them as `access_key_id:secret_key` (with the colon) and set that as `ALERTLOGIC_API_KEY`.\n\n---\n\n## Claude Code Integration (HTTP mode)\n\nStart the server in HTTP mode:\n\n```bash\nMCP_TRANSPORT=streamable-http python main.py\n```\n\nThen register it in your Claude Code project or user MCP config (`.claude/settings.json` or `~/.claude/settings.json`):\n\n```json\n{\n \"mcpServers\": {\n \"alertlogic-mcp\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:8000/mcp\"\n }\n }\n}\n```\n\nOr via the CLI:\n\n```bash\nclaude mcp add --transport http alertlogic-mcp http://localhost:8000/mcp\n```\n\n---\n\n## Claude Desktop Integration (stdio mode)\n\nEdit `claude_desktop_config.json`:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%AppData%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n \"mcpServers\": {\n \"alertlogic-mcp\": {\n \"command\": \"/absolute/path/to/.venv/bin/python\",\n \"args\": [\"/absolute/path/to/alertlogic-mcp/main.py\"]\n }\n }\n}\n```\n\n> Use absolute paths. Tilde (`~`) is not expanded by Claude Desktop. Point `command` at the venv Python, not the system Python.\n\nRestart Claude Desktop. Alert Logic tools will appear in the tool picker.\n\n---\n\n## Module Overview\n\n46 modules, ~473 tools, organized by domain:\n\n### Incident Response\n\n| Module | Tools | Key operations |\n| ---------------- | :---: | --------------------------------------------------------------------------------------- |\n| `incidents_mcp` | 11 | List, get, friendly-ID lookup, complete, reopen, add notes, add feedback, list partner incidents |\n| `soc` | 14 | Submit/poll/release SQL log searches, list exposures, get health summary |\n| `soc_playbooks` | 6 | Built-in IR guide, threat-hunt workflow, MITRE mapping, tool guides (see below) |\n\n### Asset Management\n\n| Module | Tools | Key operations |\n| ---------------- | :---: | --------------------------------------------------------------------------------------- |\n| `assets` | 15 | Query assets, get topology, declare/batch-declare/remove assets, set properties |\n| `assets_manager` | 5 | Higher-level asset management and grouping |\n| `cloud_explorer` | 12 | Browse AWS cloud resource topology by deployment |\n| `azure_explorer` | 13 | Browse Azure resource topology by deployment |\n\n### SOAR\n\n| Module | Tools | Key operations |\n| ------ | :---: | ------------------------------------------------------------------------------------------------- |\n| `soar` | 33 | List/get playbooks and actions, create/get/query executions, manage inquiries and triggers |\n\n### Vulnerabilities & Compliance\n\n| Module | Tools | Key operations |\n| -------------------- | :---: | --------------------------------------------------------------------- |\n| `vulnerability` | 10 | List exposures by severity, get per-asset exposures |\n| `vulnerabilities_kb` | 9 | Query the vulnerability knowledge base (CVE details, CVSS, remediation) |\n| `compliance` | 4 | List remediation items, conclude/dispose/undispose remediations |\n\n### Users & Authentication\n\n| Module | Tools | Key operations |\n| ------------- | :---: | ------------------------------------------------------------------------------------- |\n| `users` | 30 | Full CRUD on users, roles, access keys, MFA, and password resets |\n| `auth` | 6 | AIMS token management, list managed accounts, account ID enumeration |\n| `credentials` | 10 | IAM role and Azure AD credential CRUD, scan credentials, decrypted retrieval |\n| `themis` | 3 | Credential validation and verification |\n\n### Infrastructure & Deployments\n\n| Module | Tools | Key operations |\n| ------------------ | :---: | --------------------------------------------------------------------------- |\n| `deployments` | 5 | List, get, create, update, delete deployments |\n| `environments` | 10 | Manage Alert Logic environments and environment configuration |\n| `network_controls` | 15 | Exclusion CRUD, asset checks, tag/host whitelist management |\n| `scan_scheduler` | 13 | Create, update, and manage scan schedules per deployment |\n| `scan_result` | 4 | Retrieve and analyze scan results |\n\n### Analytics Engine\n\n| Module | Tools | Key operations |\n| ----------- | :---: | --------------------------------------------------------------------------- |\n| `aecontent` | 11 | Manage AE content (detection content library) |\n| `aefr` | 23 | AE flat-rule management |\n| `aerta` | 13 | AE real-time analytics management |\n| `aetag` | 23 | AE tag and correlation rule management |\n| `aepublish` | 1 | Publish AE analytics updates |\n| `aemanual` | 2 | Manual AE analytics operations |\n| `kalm` | 5 | AE knowledge and analytics lifecycle management |\n\n### Ticketing & Watchlist\n\n| Module | Tools | Key operations |\n| ------------------ | :---: | ------------------------------------------------------- |\n| `tickets` | 8 | Create, get, update, list, and close tickets |\n| `watchlist_module` | 7 | Manage the alerting watchlist (add, remove, query items) |\n\n### Operations & Platform\n\n| Module | Tools | Key operations |\n| --------------------- | :---: | ---------------------------------------------------------------------- |\n| `account_management` | 7 | Account details, lookup by name, parent/child relationships, topology |\n| `policies` | 2 | List and inspect policies |\n| `billing` | 12 | List and inspect subscriptions, entitlements, and billing data |\n| `common` | 22 | Herald notifications, subscriptions, webhook/email connectors, endpoints |\n| `ingest_module` | 6 | Manage log ingest sources and ingest configuration |\n| `logging_integration` | 17 | Log source CRUD, source types, collection management |\n| `otis` | 7 | On-demand threat intelligence search |\n| `notify` | 2 | Notification dispatch |\n| `search_stylist` | 2 | Log search query formatting and suggestion |\n| `informant` | 2 | Informant service queries |\n| `strawboss` | 10 | Strawboss job and schedule management |\n| `tacoma` | 12 | Tacoma service operations |\n| `album` | 10 | Evidence and artifact management |\n| `usage_module` | 4 | Account usage statistics and reporting |\n| `bulk_ops` | 2 | Cross-account bulk operations (bulk deployments, bulk health checks) |\n| `suggestions` | 10 | AI-assisted search and investigation suggestions |\n| `seceng` | — | Security Engineering: Cargo schedules/executions, AETuner analytics/tuning |\n\n---\n\n## SOC Quick Start\n\nOnce connected, try these prompts in Claude:\n\n```\nShow me all open critical incidents from the last 24 hours\n```\n\n```\nGet the elaborations (raw log evidence) for incident INC-12345\n```\n\n```\nSearch logs for SSH login failures from 10.0.0.5 in the last hour using SQL\n```\n\n```\nAdd a note to incident INC-12345: Confirmed malicious, escalating to customer\n```\n\n```\nList all deployments and their health status across all accounts\n```\n\n```\nShow me the top 10 critical vulnerabilities for host web-prod-01\n```\n\n```\nRun the SOC IR playbook to walk me through incident response steps\n```\n\n---\n\n## Built-in SOC Playbooks\n\nThe `soc_playbooks` module provides six tools that surface curated, in-context operational guides — no external documentation lookups required:\n\n| Tool | Contents |\n| --------------------------- | ------------------------------------------------------------------------------------------ |\n| `soc_ir_start` | End-to-end incident response workflow: triage checklist, scoping steps, containment criteria, evidence collection, and documentation requirements |\n| `soc_threat_hunt` | Hypothesis-driven threat-hunting playbook: IOC-based hunts, TTP-based hunts, and log query templates for common attack patterns |\n| `soc_mitre_attack_guide` | MITRE ATT&CK tactic/technique reference mapped to Alert Logic detection types and recommended search queries |\n| `soc_alertlogic_tool_guide` | Quick reference for Alert Logic MCP tools organized by investigation task (triage, scoping, evidence, containment) |\n| `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 |\n| `soc_summary` | Executive-ready incident summary template and field-population guidance |\n\nThese tools are designed to be called at the start of an investigation to load relevant context before querying live data.\n\n---\n\n## Multi-Account MSSP Usage\n\nThe server is designed for MSSP environments where a single API key manages multiple child accounts:\n\n**Partner incident listing** — `incidents_list_partner` returns incidents across all managed accounts in a single call, with account ownership labels.\n\n**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:\n\n```\nGet all open incidents for account \n```\n\n**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.\n\n**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.\n\n> **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.\n\n---\n\n## Security Notes\n\n- **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.\n- **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`:\n\n ```bash\n # Enable only incident completion workflow deletes\n ALERTLOGIC_MCP_ALLOW_DESTRUCTIVE=user_delete,playbook_execute\n ```\n\n- Every tool carries MCP `readOnlyHint`/`destructiveHint` annotations so compliant clients can apply their own confirmation policies.\n- **Never commit `.env`.** It is excluded by `.gitignore`; only `.env.example` (with placeholders) is tracked.\n- Treat `ALERTLOGIC_API_KEY` like a password. Rotate it immediately if you suspect exposure (chat logs, screen shares, lost device).\n- **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.\n- 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.\n- `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.\n- This repository ships no credentials of any kind.\n\n---\n\n## Testing\n\nA standalone smoke-test script exercises a representative cross-section of tools without going through an MCP client:\n\n```bash\npython smoke_test.py\n```\n\nThis verifies credential validity, network reachability, and base configuration before wiring the server into your MCP client.\n\n---\n\n## Troubleshooting\n\n\n\"Authentication failed\" / 401 errors
\n\n- Confirm `ALERTLOGIC_API_KEY` is the full `access_key_id:secret_key` string, including the colon separator.\n- Verify `ALERTLOGIC_BASE_URL` matches your datacenter (US `api.cloudinsight.alertlogic.com` vs. UK `api.cloudinsight.alertlogic.co.uk`).\n- Check that the access key is still active in the Alert Logic console (Manage → Users → Access Keys).\n- Confirm `ALERTLOGIC_ACCOUNT_ID` is correct — a mismatch can cause 401s on account-scoped endpoints.\n\n \n\n\nTools don't appear in Claude Desktop
\n\n- Use absolute paths in `claude_desktop_config.json`. Tilde (`~`) and relative paths are not expanded.\n- Point `command` at the virtual environment's Python (`.venv/bin/python`), not the system Python.\n- Check Claude Desktop logs for stderr output from this server: macOS logs are in `~/Library/Logs/Claude/`.\n- Restart Claude Desktop fully (quit and reopen) after editing the config file.\n\n \n\n\n\"ModuleNotFoundError: mcp\" or missing dependencies
\n\nYou 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`).\n\n \n\n\nHTTP mode: connection refused on port 8000
\n\nMake 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.\n\n \n\n\nEmpty results or silent failures
\n\nIf 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.\n\n \n\n---\n\n## Contributing\n\nPRs and issues are welcome.\n\n1. Fork the repository, create a feature branch, commit your changes, and open a PR.\n2. Add new Alert Logic endpoints as additional `@server.tool` definitions in the matching module file under `modules/`.\n3. For a new module: create `modules/.py` with a `setup(server)` function, then add it to the `MODULES` list in `main.py`.\n4. Keep tool docstrings accurate and descriptive — the docstring is what the LLM sees when deciding whether and how to call the tool.\n5. Run `python smoke_test.py` before submitting to verify basic functionality.\n\n---\n\n## Related MCP Servers\n\nThese 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.\n\n| Server | Platform | Highlights |\n|--------|----------|------------|\n| [falcon-mcp](https://github.com/rijul170/falcon-mcp) | CrowdStrike Falcon | EDR telemetry, RTR, threat intel, MSSP Flight Control, 1,296 tools |\n| [sophos-central-mcp](https://github.com/rijul170/sophos-central-mcp) | Sophos Central | Endpoint isolation, Live Discover SQL, XDR, email/firewall/DNS, 334 tools |\n| [alertlogic-mcp](https://github.com/rijul170/alertlogic-mcp) | Alert Logic MDR | Incident response, SQL log search, SOAR, vulnerability management, 473 tools |\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for full text.\n",
"bytes": 27407,
"sha": "c9e254db58a2b5682cc80d2fd929f4533837f372f85d6efa2d17f51dbd31c51a",
"repo_slug": "rijul170/alertlogic-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_rijul170_alertlogic_mcp_842f1df2/readme"
}