Elastic Security MCP

Elastic Security MCP is a Python server for the Model Context Protocol (MCP). It gives AI agents a controlled interface to Elasticsearch, Kibana Security, Fleet, and Elastic Defend.

The server is designed for investigation first: its default toolset is read-only, and response or administration actions are disabled unless the operator explicitly enables them.

Capabilities

The default toolset covers common analyst and platform-engineering workflows:

• Detection content: find detection rules, retrieve rules by stable or internal ID, preview a rule, and list installed integrations.
• Search and investigation: Elasticsearch Query DSL, EQL, ES|QL, endpoint log searches, alert retrieval, and threat-indicator lookups.
• Cluster operations: cluster health, health reports, shard-allocation explanations, snapshot status, index statistics, and ILM explanations.
• Data discovery: data streams, indices, mappings, field availability, and representative document samples.
• Endpoint and Fleet visibility: endpoint status, agents, agent policies, response-action history, and individual action details.
• Case management: cases, comments, and activity history.

Safety model

• Read-only tools are available by default.
• State-changing and endpoint-response tools are omitted until the corresponding environment flag is enabled.
• Every state-changing or endpoint action requires confirm=true in the tool call.
• Endpoint actions require a non-empty comment, which Elastic records with the action.
• Elasticsearch and Kibana permissions remain the source of truth. Use a dedicated, least-privilege service account.
• The server intentionally does not expose remote command or script execution, endpoint file retrieval, or memory-dump actions.

Requirements

• Python 3.10 or later
• uv
• Access to Elasticsearch; Kibana is required for Security, Fleet, and endpoint tools

Installation

git clone <your-repository-url>
cd MCP_elastic
uv sync --extra dev

Create a local configuration file:

# macOS or Linux
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

Set at least ELASTICSEARCH_URL and one Elasticsearch authentication method in .env. Do not commit this file. For a deployed server, use the MCP client's secret management or process environment instead.

Run the server

uv run elastic-security-mcp

The server uses standard input and output, so an MCP client starts it as a subprocess.

MCP client configuration

MCP clients use different configuration formats, but the command and environment are equivalent to the following:

{
  "mcpServers": {
    "elastic-security": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/MCP_elastic",
        "run",
        "elastic-security-mcp"
      ],
      "env": {
        "ELASTICSEARCH_URL": "https://your-cluster.example:9243",
        "ELASTICSEARCH_API_KEY": "your-api-key",
        "KIBANA_URL": "https://your-kibana.example:5601",
        "KIBANA_SPACE": "default"
      }
    }
  }
}

On Windows, use the absolute Windows path to the repository. Keep credentials in the client secret store or environment where possible.

Optional action tools

Action tools must be enabled by the server operator. All of them require confirm=true.

Area	Tools	Required environment setting
Device containment	isolate_device, release_device	ELASTIC_MCP_ENABLE_RESPONSE_ACTIONS=true
Process control	stop_process, pause_process	Response actions plus ELASTIC_MCP_ENABLE_PROCESS_ACTIONS=true
Endpoint evidence collection	request_running_processes, scan_endpoint_path	Response actions plus ELASTIC_MCP_ENABLE_ENDPOINT_COLLECTION_ACTIONS=true
Cases	create_case, add_case_comment, update_case	ELASTIC_MCP_ENABLE_CASE_ACTIONS=true
Alert triage	set_detection_alert_status, set_detection_alert_tags, set_detection_alert_assignees	ELASTIC_MCP_ENABLE_ALERT_ACTIONS=true
Detection-rule activation	set_detection_rules_enabled	ELASTIC_MCP_ENABLE_RULE_ACTIONS=true
Fleet lifecycle	request_agent_diagnostics, update_fleet_agent_tags, upgrade_fleet_agent, reassign_fleet_agent, unenroll_fleet_agent	ELASTIC_MCP_ENABLE_FLEET_ACTIONS=true

preview_detection_rule is always read-only. Alert assignment uses Kibana user profile IDs, and rule activation uses the internal rule id returned by search_detection_rules, not the stable rule_id.

Configuration

Variable	Required	Description
ELASTICSEARCH_URL	Yes	Elasticsearch base URL.
ELASTICSEARCH_API_KEY	One auth method	Elasticsearch API key.
ELASTICSEARCH_USERNAME and ELASTICSEARCH_PASSWORD	One auth method	Alternative basic authentication.
KIBANA_URL	For Kibana tools	Kibana base URL.
KIBANA_API_KEY	No	Separate Kibana API key; otherwise the Elasticsearch key is reused.
KIBANA_USERNAME and KIBANA_PASSWORD	No	Alternative Kibana basic authentication.
KIBANA_SPACE	No	Kibana space; defaults to default.
ELASTIC_VERIFY_CERTS	No	TLS validation; defaults to true.
ELASTIC_REQUEST_TIMEOUT_SECONDS	No	HTTP request timeout; defaults to 30.
ELASTIC_MCP_ALLOW_GLOBAL_INDEX_PATTERNS	No	Permits * and _all; defaults to false.
ELASTIC_MCP_MAX_SEARCH_RESULTS	No	Maximum results returned by bounded search tools; defaults to 100.
ELASTIC_MCP_ENABLE_RESPONSE_ACTIONS	No	Enables device isolation and release.
ELASTIC_MCP_ENABLE_PROCESS_ACTIONS	No	Enables process termination and suspension.
ELASTIC_MCP_ENABLE_ENDPOINT_COLLECTION_ACTIONS	No	Enables process listing and malware scans.
ELASTIC_MCP_ENABLE_CASE_ACTIONS	No	Enables case creation, comments, and updates.
ELASTIC_MCP_ENABLE_ALERT_ACTIONS	No	Enables alert status, tag, and assignment updates.
ELASTIC_MCP_ENABLE_FLEET_ACTIONS	No	Enables Fleet diagnostics and lifecycle changes.
ELASTIC_MCP_ENABLE_RULE_ACTIONS	No	Enables detection-rule activation changes.
ELASTIC_MCP_AUDIT_LOG_PATH	No	Writes a local JSONL audit trail for Kibana mutations.

Detection-rule changes can update the API key assigned to those rules. Ensure that the credential used by this MCP server has the correct, least-privilege permissions before enabling rule actions.

Audit logging

Set ELASTIC_MCP_AUDIT_LOG_PATH to retain a local record of Kibana mutation requests:

ELASTIC_MCP_AUDIT_LOG_PATH=./logs/elastic-security-mcp-audit.jsonl

Each line contains a timestamp, request method, path, outcome, and HTTP status when available. Request bodies and credentials are not written to the log. Protect the log directory because resource identifiers can still be sensitive operational data.

Development

uv run pytest
uv run ruff check .
uv run ruff format --check .

The test suite covers configuration validation, safety helpers, audit-log behavior, and MCP stdio tool registration. It does not make requests to a live Elastic deployment.

Before a public release

Choose and add a license before publishing a reusable public repository. MIT and Apache-2.0 are common options, but the choice should match the intended maintenance and contribution model.