# Elastic MCP Server

A comprehensive MCP (Model Context Protocol) server for Elasticsearch with InfoSec-focused tools for security management, search operations, index management, and cluster monitoring.

## Features

- **Security Management**: Users, roles, API keys, privileges
- **Search & Query**: Full-text search, ES|QL, aggregations
- **Index Operations**: List, create, delete, mappings, settings
- **Cluster Monitoring**: Health, stats, nodes, shards
- **Cross-Platform**: Works on Windows, macOS, and Linux

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment

Copy `.env.example` to `.env` and configure your Elasticsearch connection:

```bash
# macOS/Linux
cp .env.example .env

# Windows (Command Prompt)
copy .env.example .env

# Windows (PowerShell)
Copy-Item .env.example .env
```

Edit `.env` with your credentials:

```bash
# Elasticsearch endpoint
ELASTIC_URL=https://your-deployment.es.region.azure.elastic-cloud.com

# API Key authentication (recommended)
ELASTIC_API_KEY_ENCODED=your-base64-encoded-api-key
```

### 3. Build

```bash
npm run build
```

### 4. Run

```bash
npm start
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ELASTIC_URL` | Yes | Elasticsearch cluster URL |
| `ELASTIC_API_KEY_ENCODED` | Yes* | Pre-encoded API key (base64) |
| `ELASTIC_API_KEY_ID` | Yes* | API key ID (alternative to encoded) |
| `ELASTIC_API_KEY_SECRET` | Yes* | API key secret (use with ID) |
| `ELASTIC_USERNAME` | Yes* | Basic auth username |
| `ELASTIC_PASSWORD` | Yes* | Basic auth password |
| `ELASTIC_SKIP_SSL_VERIFY` | No | Skip SSL verification (default: false) |
| `ELASTIC_TIMEOUT` | No | Request timeout in ms (default: 30000) |
| `LOG_LEVEL` | No | Logging level (default: info) |

*One authentication method is required: encoded API key, ID+secret, or username+password.

### Authentication Methods

#### API Key (Recommended)

Use the pre-encoded API key from the Elasticsearch API key creation response:

```bash
ELASTIC_API_KEY_ENCODED=YWNCT3hKc0JjVEtMYUN5ZWVNa046UGR4OUxwOFRtY2R5WElfTjBvMEhrQQ==
```

#### Separate ID and Secret

If you have the raw ID and secret:

```bash
ELASTIC_API_KEY_ID=acBOxJsBcTKLaCyeeMkN
ELASTIC_API_KEY_SECRET=Pdx9Lp8TmcdyXI_N0o0HkA
```

#### Basic Auth (Not Recommended)

```bash
ELASTIC_USERNAME=elastic
ELASTIC_PASSWORD=your-password
```

## Available Tools

### Search Tools (5 tools)

| Tool | Description |
|------|-------------|
| `search` | Execute search queries using Elasticsearch Query DSL |
| `esql_query` | Execute ES\|QL queries for data analysis |
| `get_document` | Retrieve a specific document by ID |
| `count` | Count documents matching a query |
| `msearch` | Execute multiple search queries in one request |

### Security Tools (12 tools)

| Tool | Description |
|------|-------------|
| `list_users` | List all users in the security realm |
| `get_user` | Get detailed user information |
| `create_user` | Create a new user with roles |
| `delete_user` | Delete a user |
| `set_user_enabled` | Enable or disable a user |
| `list_roles` | List all defined roles |
| `get_role` | Get role details |
| `create_role` | Create or update a role |
| `delete_role` | Delete a role |
| `list_api_keys` | List API keys |
| `create_api_key` | Create a new API key |
| `invalidate_api_key` | Invalidate API keys |
| `get_privileges` | Get current user privileges |
| `has_privileges` | Check specific privileges |
| `authenticate` | Get current authenticated user info |

### Index Tools (9 tools)

| Tool | Description |
|------|-------------|
| `list_indices` | List all indices with health and stats |
| `get_index` | Get index details |
| `get_mappings` | Get field mappings |
| `get_settings` | Get index settings |
| `create_index` | Create a new index |
| `delete_index` | Delete an index (requires confirmation) |
| `refresh_index` | Refresh an index |
| `get_index_stats` | Get index statistics |
| `get_aliases` | Get index aliases |

### Cluster Tools (8 tools)

| Tool | Description |
|------|-------------|
| `cluster_health` | Get cluster health status |
| `cluster_stats` | Get comprehensive cluster statistics |
| `cluster_info` | Get basic cluster info and version |
| `nodes_info` | Get node information |
| `nodes_stats` | Get node statistics |
| `pending_tasks` | List pending cluster tasks |
| `allocation_explain` | Explain shard allocation |
| `get_shards` | Get shard allocation details |

## Usage Examples

### Search for Security Events

```json
{
  "tool": "search",
  "arguments": {
    "index": "logs-*",
    "query": {
      "bool": {
        "must": [
          { "match": { "event.category": "authentication" } },
          { "match": { "event.outcome": "failure" } }
        ]
      }
    },
    "size": 100,
    "sort": [{ "@timestamp": "desc" }]
  }
}
```

### List All Users

```json
{
  "tool": "list_users",
  "arguments": {}
}
```

### Check Cluster Health

```json
{
  "tool": "cluster_health",
  "arguments": {
    "level": "indices"
  }
}
```

### Create an API Key

```json
{
  "tool": "create_api_key",
  "arguments": {
    "name": "my-api-key",
    "expiration": "30d",
    "role_descriptors": {
      "read-only": {
        "cluster": ["monitor"],
        "indices": [{
          "names": ["logs-*"],
          "privileges": ["read"]
        }]
      }
    }
  }
}
```

## Development

### Run Tests

```bash
npm test
```

### Run Tests with Coverage

```bash
npm run test:coverage
```

### Lint

```bash
npm run lint
```

### Watch Mode

```bash
npm run dev
```

## Claude Desktop Integration

### macOS / Linux

Config location: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/claude/claude_desktop_config.json` (Linux)

```json
{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["/path/to/elastic-mcp/dist/index.js"],
      "env": {
        "ELASTIC_URL": "https://your-deployment.es.region.azure.elastic-cloud.com",
        "ELASTIC_API_KEY_ENCODED": "your-encoded-api-key"
      }
    }
  }
}
```

### Windows

Config location: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "elastic": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\elastic-mcp\\dist\\index.js"],
      "env": {
        "ELASTIC_URL": "https://your-deployment.es.region.azure.elastic-cloud.com",
        "ELASTIC_API_KEY_ENCODED": "your-encoded-api-key"
      }
    }
  }
}
```

**Windows Notes:**
- Use double backslashes (`\\`) in JSON paths, or forward slashes (`/`) which also work
- Ensure Node.js is installed and available in your PATH
- Run `npm install` and `npm run build` before first use

## Security Considerations

- API keys are never logged or exposed in responses
- All credentials must be provided via environment variables
- SSL certificate verification is enabled by default
- The `delete_index` tool requires explicit confirmation
- Created API keys return the encoded value but not the raw secret

## License

MIT