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.

text

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
Detection 360 report list (false positives and missed attacks)
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
Detection 360 report submit (false positive, missed attack/spam/graymail) 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.

server.ts

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

Installation

From source

bash

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

Docker

Terminal

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

27 read tools are always registered. With ABNORMAL_ALLOW_EVIDENCE_DOWNLOAD=true, five evidence tools are added (32 total). With ABNORMAL_ALLOW_RESPONSE=true, four response tools are added (31 total, or 36 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`
Detection 360	`abnormal_detection360_reports_list`
URL rewrite	`abnormal_url_rewrite_clicks_list`
Audit logs	`abnormal_audit_logs_list`
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`, `abnormal_detection360_report_submit`

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

bash

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.