Abnormal MCP Server

A secure, open-source Model Context Protocol server for Abnormal Security.

This project is not an official Abnormal product and is not endorsed by Abnormal AI.

Overview

abnormal-mcp lets MCP clients such as Cursor and Claude Desktop query Abnormal Security over stdio (default) or Streamable HTTP. It uses a lightweight handwritten client against the Abnormal Security Client API.

MCP Client
    → Abnormal MCP Server (stdio or HTTP)
        → Abnormal REST API

The server is read-only by default. Response and evidence download tools are opt-in and independent. Abnormal authorization still applies to every request.

Related MCP server: Purple AI MCP Server

Features

Read (always on)

• Threat list and get from the Threat Log

• Threat links and attachment metadata

• Threat action status poll (abnormal_threat_action_get)

• Message search with ergonomic filters (since, sender, sender_domain, recipient, subject, url, attachment, sender_ip, judgement)

• Search activity list and status

• Message remediation history

• AI Security Mailbox (formerly Abuse Mailbox) campaigns and unanalyzed reports

• Employee profile, identity (Genome), and recent logins

• ATO case list, detail, and analysis

• Vendor list, detail, activity, and vendor compromise cases

• US, EU, and FedRAMP base URLs (configurable)

Response (opt-in: ABNORMAL_ALLOW_RESPONSE=true)

• Search remediation (delete, move_to_inbox) with confirm: true preview gate

• Threat remediate / unremediate with confirm: true preview gate

• ATO case status update with confirm: true preview gate

Evidence download (opt-in: ABNORMAL_ALLOW_EVIDENCE_DOWNLOAD=true)

• Message EML download (by ABX message ID or search cloud_message_id)

• Attachment analysis signals and attachment download

• Metadata + bounded preview by default; optional base64 embed (max 1 MiB in tool output)

• stdio transport (default) and opt-in Streamable HTTP

• Native Go binary and Docker image

• MCP Registry listing on tagged releases (io.github.GregDog/mcp-server-abnormal)

Quick Start

Create an Abnormal REST API token in the Abnormal portal under Integrations → Abnormal REST API.

export ABNORMAL_API_TOKEN="your-token"
abnormal-mcp serve

Installation

From source

git clone https://github.com/GregDog/mcp-server-abnormal.git
cd mcp-server-abnormal
make build

Docker

docker run --rm -i \
  -e ABNORMAL_API_TOKEN \
  ghcr.io/gregdog/mcp-server-abnormal serve

Client configuration

Cursor (stdio)

See examples/cursor.mcp.json.

Claude Desktop

See examples/claude-desktop.json.

Tools

24 read tools are always registered. With ABNORMAL_ALLOW_EVIDENCE_DOWNLOAD=true, five evidence tools are added (29 total). With ABNORMAL_ALLOW_RESPONSE=true, three response tools are added (27 total, or 32 with both gates enabled).

See docs/tools.md for parameters.

Configuration

Full list: docs/configuration.md.

Security

Read tools are always on. Response and evidence tools require explicit opt-in.

Local use only: this server has no built-in authentication or RBAC. Use stdio (default) or loopback HTTP on the same machine. Do not expose the HTTP endpoint on a network without your own access controls.

See docs/security.md and SECURITY.md.

Development

make check
make test-access    # optional live API smoke test
make test-phase34   # Phase 3/4 live smoke test
make test-phase5    # Phase 5 evidence smoke test (requires ABNORMAL_ALLOW_EVIDENCE_DOWNLOAD)

See docs/development.md.

License

Apache-2.0. See LICENSE.