Abnormal MCP Server

License

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.

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).

Area	Tools
Threats	`abnormal_threats_list`, `abnormal_threat_get`, `abnormal_threat_action_get`, `abnormal_threat_links_list`, `abnormal_threat_attachments_list`
Search	`abnormal_search_messages`, `abnormal_search_activities_list`, `abnormal_search_activity_get`
Messages	`abnormal_message_remediation_history`
Mailbox	`abnormal_mailbox_campaigns_list`, `abnormal_mailbox_campaign_get`, `abnormal_mailbox_unanalyzed_list`
Employees	`abnormal_employee_get`, `abnormal_employee_identity_get`, `abnormal_employee_logins_list`
ATO cases	`abnormal_cases_list`, `abnormal_case_get`, `abnormal_case_analysis_get`, `abnormal_case_action_get`
Vendors	`abnormal_vendors_list`, `abnormal_vendor_get`, `abnormal_vendor_activity_list`, `abnormal_vendor_cases_list`, `abnormal_vendor_case_get`
Evidence (opt-in)	`abnormal_message_eml_get`, `abnormal_search_message_eml_get`, `abnormal_message_attachment_get`, `abnormal_message_attachment_download`, `abnormal_search_attachment_download`
Response (opt-in)	`abnormal_search_remediate`, `abnormal_threat_remediate`, `abnormal_case_update`

See docs/tools.md for parameters.

Configuration

Variable	Default	Purpose
`ABNORMAL_API_TOKEN`	(required)	Bearer token
`ABNORMAL_BASE_URL`	`https://api.abnormalplatform.com/v1`	API base URL
`ABNORMAL_ALLOW_RESPONSE`	`false`	Enable response tools (Phase 2+)
`ABNORMAL_ALLOW_EVIDENCE_DOWNLOAD`	`false`	Enable evidence download (Phase 5+)
`ABNORMAL_MCP_TRANSPORT`	`stdio`	`stdio` or `http`

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.