# ZeroSOC MCP Servers

**Model Context Protocol (MCP) servers, and the typed tool clients they wrap, for security operations.**

MCP servers are the integration layer that lets AI agents query security platforms directly — the source of truth — instead of copying telemetry into yet another data lake. This repository is the [ZeroSOC Framework](https://github.com/ZeroSOC/zerosoc-framework) community's home for MCP servers covering major security technologies that lack an official or complete one.

## Operating model

For each security technology we pick exactly one engagement mode:

| Mode | When | What we do |
|---|---|---|
| **Adopt** | An official vendor (or healthy third-party) MCP server exists and is adequate | Reference it via its package manager distribution. We never fork-and-diverge. |
| **Contribute** | A server exists but is partial | Contribute enhancements upstream, under the upstream project's license and governance. |
| **Build** | No usable server exists | Build and maintain it here — vendor-neutral, permissively licensed, production-quality. |

**Sunset policy:** when a vendor ships an official server for a technology we Build, we converge — we contribute our learnings and tests upstream, put our server in maintenance mode with a migration note, and offer to donate the codebase to the vendor. The goal is ecosystem health, not ownership.

## Coverage registry

| Technology | Mode | Status | Server / upstream |
|---|---|---|---|
| Microsoft security (Defender XDR, Defender for Endpoint, Entra ID, Purview Audit) | **Build** | Active | [`servers/microsoft-security`](servers/microsoft-security/) |
| AbuseIPDB (IP reputation, blacklist) | **Adopt** | Active | Agents: AbuseIPDB's own [`mcp-server-abuseipdb`](https://github.com/AbuseIPDB/AbuseIPDB-MCP). Hosts calling from code: the tool client [`clients/abuseipdb`](clients/abuseipdb/) (check with cache and quota, blacklist matched locally) |
| Google SecOps (Chronicle) | Contribute | Planned | Official server exists but is partial; upstream contributions being scoped |
| CrowdStrike Falcon | Adopt | Evaluating | Official/third-party options under evaluation |
| Microsoft Sentinel | — | Candidate | Not yet scoped |

Want a technology covered? [Open an issue](../../issues) with the vendor, the API surface, and links to any existing MCP servers.

## One technology, two parts

Every integration built here ships as a **tool client** (`clients/<technology>/`, a typed Python library) and an **MCP server** (`servers/<technology>/`) that is a thin wrapper over it. Where the technology's own server is adopted, only the client lives here, for hosts that call the API from code (AbuseIPDB). Agents use the server from any MCP host; programs call the client directly where the path must be deterministic. Each API call is implemented once, so both see the same behaviour. Each server also ships a **capabilities manifest** and, where the technology allows it, a **capability probe** that writes a ZeroSOC capability binding file for what a given tenant exposes.

Servers run standalone. The server and its tool client are two packages in this repository, so both are named on the command line:

```bash
uvx --from "git+https://github.com/ZeroSOC/zerosoc-mcp@<tag>#subdirectory=servers/<technology>" \
    --with "git+https://github.com/ZeroSOC/zerosoc-mcp@<tag>#subdirectory=clients/<technology>" \
    <command>
```

## Quality bar

Every server built here meets the same bar:

- **Safe by default** — read tools and response/write tools are separated; destructive response actions are disabled unless explicitly enabled per deployment via an environment flag.
- **Context-friendly** — every list tool paginates with sane caps; no unbounded dumps into an agent's context window.
- **Actionable errors** — API failures surface the status and a remediation hint (e.g. the exact missing permission).
- **No secrets** — configuration via environment variables only, documented in each server's `.env.example`; required API permissions are documented per tool group.

## Servers

### [`servers/microsoft-security`](servers/microsoft-security/) — Microsoft security

Incidents with their full evidence inventory, alerts, cross-workload advanced hunting, Entra ID logs and the Microsoft 365 unified audit log (Microsoft Purview Audit) via **Microsoft Graph**, a capability probe, plus device response actions, threat indicators, and vulnerability management via the Microsoft Defender for Endpoint API. See its [README](servers/microsoft-security/README.md) for setup, and [`clients/microsoft-security`](clients/microsoft-security/) for the tool client.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions are accepted under Apache 2.0 with [DCO](https://developercertificate.org/) sign-off (`git commit -s`); there is no CLA. Taking part means keeping to the [Code of Conduct](CODE_OF_CONDUCT.md).

Please do not put real tenant data in an issue or a pull request — no device or user names, tenant identifiers, hashes or incident exports.

## Security

Found a vulnerability? **Do not open a public issue.** See [SECURITY.md](SECURITY.md) for private reporting and what is in scope.

## License

[Apache 2.0](LICENSE). Portions derived from MIT-licensed prior work — see [NOTICE](NOTICE).