# Cybersecurity MCP Server

A production-style MCP (Model Context Protocol) server that gives AI models a toolkit of real cybersecurity capabilities — port scanning, WHOIS, DNS, threat intelligence, CVE lookup, and more.

```
Claude / ChatGPT
      │
Model Context Protocol
      │
Cyber MCP Server
      │
 ┌────┬────┬──────┬──────┬─────┬───────┬────────┐
Nmap DNS  WHOIS  VT   ABUSE  NVD  Hash   URL
```

---

## Tools

| Tool | What it does | External API |
|---|---|---|
| `scan_host` | Nmap TCP scan on a single host | — |
| `scan_range` | Nmap sweep across a CIDR block | — |
| `whois_lookup` | Registrar, dates, nameservers | — |
| `dns_lookup` | A/AAAA/MX/NS/TXT/CNAME/SOA records | — |
| `check_ip_reputation` | Malicious flag, abuse score, ISP | VirusTotal, AbuseIPDB |
| `check_url_reputation` | Detection ratio, categories | VirusTotal |
| `analyze_hash` | MD5/SHA1/SHA256 file hash lookup | VirusTotal |
| `search_cve` | CVSS score, description, CPEs | NVD (NIST) |
| `check_password_strength` | zxcvbn score, entropy, crack time | — (fully local) |
| `scan_url` | SSL cert, redirect chain, risk score | — |

---

## Quick start

### 1. Clone & install

```bash
git clone https://github.com/yourname/cyber-mcp-server.git
cd cyber-mcp-server

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
```

### 2. Configure

```bash
cp .env.example .env
# Edit .env — add your API keys
```

### 3. Run (stdio — for Claude Desktop)

```bash
python server.py
```

### 4. Run (SSE — for HTTP clients)

```bash
MCP_TRANSPORT=sse python server.py
# Server starts on http://0.0.0.0:8000
```

### 5. Docker

```bash
docker compose up --build
```

---

## Claude Desktop integration

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cyber": {
      "command": "python",
      "args": ["/absolute/path/to/cyber-mcp-server/server.py"],
      "env": {
        "API_KEYS": "your-key",
        "VIRUSTOTAL_API_KEY": "...",
        "ABUSEIPDB_API_KEY": "...",
        "NVD_API_KEY": "..."
      }
    }
  }
}
```

---

## Example prompts (in Claude)

```
Scan scanme.nmap.org and summarize the open services.
Is 185.220.101.1 a malicious IP?
Look up CVE-2024-3400 and explain the risk.
Check the password "Summer2024!" — is it strong?
Analyse the hash d41d8cd98f00b204e9800998ecf8427e.
Scan https://example.com for SSL and security header issues.
Do a full DNS lookup for google.com.
```

---

## Project structure

```
cyber-mcp-server/
├── server.py                   # Entry point — registers all tools
├── config/
│   └── settings.py             # Env-based configuration
├── tools/
│   ├── nmap_tool.py            # Port scanner
│   ├── whois_tool.py           # WHOIS lookup
│   ├── dns_tool.py             # DNS records
│   ├── vt_tool.py              # VirusTotal / AbuseIPDB
│   ├── hash_tool.py            # File hash analysis
│   ├── cve_tool.py             # NVD CVE lookup
│   ├── password_tool.py        # Password strength (local)
│   └── url_tool.py             # SSL + redirect + header scan
├── middleware/
│   ├── auth.py                 # API key + JWT auth
│   ├── rate_limit.py           # Token-bucket rate limiter
│   └── audit.py                # Structured JSON audit logs
├── utils/
│   └── helpers.py              # Shared utilities
├── tests/
│   └── test_tools.py           # Pytest unit tests
├── logs/                       # Auto-created at runtime
├── .env.example                # Environment variable template
├── .github/workflows/ci.yml    # GitHub Actions CI/CD
├── Dockerfile
├── docker-compose.yml
├── pytest.ini
└── requirements.txt
```

---

## API keys needed

| Service | Get key | Free tier |
|---|---|---|
| VirusTotal | https://virustotal.com | 4 req/min |
| AbuseIPDB | https://abuseipdb.com | 1000 req/day |
| NVD (NIST) | https://nvd.nist.gov/developers/request-an-api-key | 50 req/30s |

---

## Testing

```bash
pytest tests/ -v --cov=. --cov-report=term-missing
```

---

## Security notes

- **Nmap scans** should only target hosts you have permission to scan.
- Passwords evaluated by `check_password_strength` are **never logged or sent externally**.
- All tool calls are written to `logs/audit.log` as newline-delimited JSON.
- Run the container as a non-root user (already configured in `Dockerfile`).
- Rotate `API_KEYS` and `JWT_SECRET` before deploying to production.

---

## Resume features checklist

- [x] MCP + FastMCP integration
- [x] 8 cybersecurity tools
- [x] API key authentication
- [x] JWT token support
- [x] Rate limiting (token bucket)
- [x] Structured audit logging
- [x] Docker + docker-compose
- [x] GitHub Actions CI/CD
- [x] Pytest unit tests with coverage
- [x] Async throughout (httpx, asyncio)
- [x] Secure non-root Docker image
- [x] `.env`-based configuration
"# cyber-mcp-server"