# taegis-magic-mcp

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps
[taegis-magic](https://github.com/secureworks/taegis-magic) — the Secureworks Taegis XDR
CLI and SDK — so that AI assistants and agents can query alerts, events, investigations,
threat intelligence, and tenants directly from their context window.

## How it works

[taegis-magic](https://github.com/secureworks/taegis-magic) is the official open-source
CLI and SDK for Secureworks Taegis XDR. It exposes subcommands like
`taegis alerts search`, `taegis investigations search`, `taegis events search`, etc. via
a rich Python SDK backed by the Taegis GraphQL API.

This server wraps those CLI commands behind the MCP tool protocol: an agent calls a tool
(`search_alerts`, `search_events`, …), the server runs the appropriate `taegis` command as
a subprocess, and returns the JSON output to the agent. No Taegis API knowledge is required
on the agent side.

```
Agent / LLM
    │
    │  MCP tool call: search_alerts(query="...", region="charlie")
    ▼
taegis-magic-mcp  (this server)
    │
    │  subprocess: taegis alerts search --cell "..." --region charlie --limit 100
    ▼
taegis-magic CLI  ─────► Secureworks Taegis XDR API
```

## Requirements

| Requirement | Notes |
|---|---|
| Python ≥ 3.11 | |
| [uv](https://docs.astral.sh/uv/) | Used to run the server in an isolated environment |
| [taegis-magic](https://github.com/secureworks/taegis-magic) | Must be installed and on `PATH` — `pip install taegis-magic` |

## Authentication

taegis-magic supports two authentication methods:

### OAuth client credentials (recommended for automated use)

```bash
export TAEGIS_CLIENT_ID=<your-oauth-client-id>
export TAEGIS_CLIENT_SECRET=<your-oauth-client-secret>
export TAEGIS_ENVIRONMENT=<region>   # charlie | delta | us1 | us2 | eu
```

The MCP server forwards these as `CLIENT_ID` / `CLIENT_SECRET` to the
[taegis-sdk-python](https://github.com/secureworks/taegis-sdk-python) environment
(the names the SDK reads). `TAEGIS_CLIENT_ID` / `TAEGIS_CLIENT_SECRET` are the
namespaced forms used here to avoid collisions with other tools.

### Interactive login (recommended for interactive use)

```bash
taegis auth login
```

The cached token is stored at `~/.taegis_sdk_python/config` and reused automatically.

## Available MCP tools

| Tool | Description |
|---|---|
| `search_alerts` | Search Taegis alerts using OCSF query syntax |
| `search_events` | Search Taegis security events |
| `search_investigations` | List open security investigations |
| `search_threat_intel` | Search threat intelligence (IOCs, hashes, IPs, domains …) |
| `list_tenants` | List all tenants visible to the authenticated user |
| `run_taegis_command` | Escape hatch — run any `taegis` CLI subcommand and return JSON |

All tools accept an optional `region` parameter (overrides `TAEGIS_ENVIRONMENT`).

### Example queries

```
search_alerts(query="FROM alert EARLIEST=-1d WHERE severity='High'", region="charlie")
search_events(query="FROM event EARLIEST=-4h WHERE source_ip='10.0.0.1'")
search_threat_intel(query="evil.example.com")
run_taegis_command(args="rules search --region charlie --limit 10")
```

## Installation

### With opencode

Clone or add this repo as a submodule, then add to your `opencode.jsonc`:

```jsonc
"mcp": {
  "taegis": {
    "type": "local",
    "command": ["uv", "run", "--project", "/path/to/taegis-magic-mcp", "taegis-mcp"],
    "environment": {
      "TAEGIS_CLIENT_ID": "${TAEGIS_CLIENT_ID}",
      "TAEGIS_CLIENT_SECRET": "${TAEGIS_CLIENT_SECRET}",
      "TAEGIS_ENVIRONMENT": "${TAEGIS_ENVIRONMENT}"
    },
    "enabled": false
  }
}
```

Set `"enabled": true` (or toggle at runtime) when you want the Taegis tools in scope.

### Standalone

```bash
git clone https://github.com/DarkLicornor/taegis-magic-mcp.git
cd taegis-magic-mcp
uv sync
uv run taegis-mcp
```

## Development

```bash
git clone https://github.com/DarkLicornor/taegis-magic-mcp.git
cd taegis-magic-mcp
uv sync --extra dev
uv run taegis-mcp        # run the server
uv run pytest            # run tests
uv run ruff check .      # lint
uv run mypy src          # type-check
```

## See also

- [taegis-magic](https://github.com/secureworks/taegis-magic) — the underlying Taegis CLI / SDK this server wraps
- [taegis-sdk-python](https://github.com/secureworks/taegis-sdk-python) — the Python SDK taegis-magic is built on
- [Model Context Protocol](https://modelcontextprotocol.io/) — the protocol this server implements
- [FastMCP](https://github.com/jlowin/fastmcp) — the MCP server framework used

## License

MIT