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.

Related MCP server: opensearch-mcp-server-py

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.

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

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.