# 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](https://docs.astral.sh/uv/)
- Access to Elasticsearch; Kibana is required for Security, Fleet, and endpoint tools

## Installation

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

Create a local configuration file:

```bash
# 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

```bash
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:

```json
{
  "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:

```dotenv
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

```bash
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.