# CyberMCP

An MCP (Model Context Protocol) server that gives Claude cybersecurity research tools.

## Tools

| Tool | Source | Auth |
|------|--------|------|
| `cve_lookup` | NVD API | None required |
| `ip_lookup` | ip-api.com | None required |
| `hash_check` | VirusTotal API | Free API key |

### cve_lookup
Look up any CVE by ID. Returns description, CVSS score, severity, vector string, and references.

**Example:** `CVE-2021-44228` (Log4Shell)

### ip_lookup
Geolocate an IPv4 or IPv6 address. Returns country, city, ISP, ASN, timezone, and proxy/VPN detection.

**Example:** `8.8.8.8`

### hash_check
Check a file hash (MD5, SHA-1, or SHA-256) against VirusTotal. Returns verdict, detection ratio, file type, and threat names.

**Example:** `44d88612fea8a8f36de82e1278abb02f` (EICAR test file MD5)

## Installation

```bash
cd cybermcp
pip install -r requirements.txt
```

Set up your VirusTotal API key:

```bash
cp .env.example .env
# Edit .env and add your VIRUSTOTAL_API_KEY
```

Get a free VirusTotal API key at https://www.virustotal.com/gui/join-us

## Running the server

```bash
python main.py
```

## Connecting to Claude Desktop

Add the following to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "cybermcp": {
      "command": "python",
      "args": ["/absolute/path/to/cybermcp/main.py"]
    }
  }
}
```

Config file locations:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

## Connecting to Claude Code (CLI)

```bash
claude mcp add cybermcp python /absolute/path/to/cybermcp/main.py
```

## Project Structure

```
cybermcp/
├── main.py           # MCP server entry point
├── tools/
│   ├── __init__.py   # Exports all tools
│   ├── cve.py        # NVD CVE lookup
│   ├── ip_lookup.py  # ip-api.com geolocation
│   └── hash_check.py # VirusTotal hash analysis
├── .env.example      # API key template
├── requirements.txt
└── README.md
```