# CyberMCP

**A free, open-source [Model Context Protocol](https://modelcontextprotocol.io)
server that gives AI assistants a toolbox of recon and defensive
cybersecurity tools.**

Point Claude Desktop, Claude Code, or any other MCP-compatible client at
CyberMCP and it can look up DNS records, enumerate subdomains from
certificate transparency logs, check TLS certificate expiry, audit HTTP
security headers, look up CVEs, identify hash formats, estimate password
strength, and more — all through natural conversation.

> ⚠️ **Scope:** CyberMCP is for **authorized** security testing, OSINT, and
> education. It ships no exploits and no attack automation. See
> [SECURITY.md](SECURITY.md) for the responsible-use policy.

## Features

- 🔎 **DNS & WHOIS** — `dns_lookup`, `reverse_dns`, `whois_lookup`
- 🕵️ **Passive OSINT** — `enumerate_subdomains` via certificate transparency (crt.sh), zero contact with the target
- 🔐 **TLS inspection** — `check_ssl`: validity, expiry, issuer, SANs, cipher/version
- 🛡️ **HTTP security headers** — `check_http_security_headers`: HSTS, CSP, X-Frame-Options, and more, with a 0–100 score
- 🧪 **CVE intel** — `lookup_cve`, `search_cves` against the NIST NVD API
- 🧰 **Offline toolbox** — `compute_hashes`, `identify_hash`, `estimate_password_strength`, `encode_text`/`decode_text`
- 🚧 **Authorization-gated port scanning** — `scan_ports` refuses to run unless explicitly told `authorized=True`
- ✅ Full pytest suite, ruff lint, matrixed CI across Python 3.10–3.12, tagged releases auto-published via GitHub Actions

See [docs/TOOLS.md](docs/TOOLS.md) for the full tool reference.

## Quick start

```bash
git clone https://github.com/Dacraezy1/CyberMCP.git
cd CyberMCP
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
```

Add it to Claude Desktop's config (see [docs/INSTALL.md](docs/INSTALL.md) for
full details and Claude Code instructions):

```json
{
  "mcpServers": {
    "cybermcp": {
      "command": "/absolute/path/to/CyberMCP/.venv/bin/python",
      "args": ["-m", "cybermcp.server"]
    }
  }
}
```

Restart Claude Desktop, then just ask:

> "Check the SSL cert on example.com and tell me when it expires."
>
> "Search NVD for CVEs related to Log4j."
>
> "What does crt.sh show for subdomains of my-domain.org?"

More examples in [docs/USAGE.md](docs/USAGE.md).

## Project layout

```
CyberMCP/
├── cybermcp/
│   ├── server.py          # MCP server + tool registration (FastMCP)
│   └── tools/              # One module per tool, independently testable
├── tests/                   # pytest suite
├── docs/                    # INSTALL.md, USAGE.md, TOOLS.md
├── examples/                 # Claude Desktop config example
└── .github/workflows/        # ci.yml (lint+test+build), release.yml (tag → GitHub Release)
```

## Development

```bash
pip install -e ".[dev]"
pytest -v
ruff check .
```

Pushing a tag like `v0.1.0` triggers the release workflow, which builds the
package and publishes it as a GitHub Release with the wheel/sdist attached.

## Contributing

PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for what's in/out of
scope and how to add a new tool. Please read [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
and [SECURITY.md](SECURITY.md) first.

## License

[MIT](LICENSE) © Younes ([Dacraezy1](https://github.com/Dacraezy1))