# 🛡️ ThreatWatch MCP

**AI-Powered Threat Intelligence with Real-Time Alert Monitoring**

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that brings multi-source
threat intelligence directly into Claude Desktop and any MCP-compatible AI assistant.

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![MCP](https://img.shields.io/badge/MCP-compatible-green.svg)](https://modelcontextprotocol.io)

---

## ✨ What Makes ThreatWatch Different

| Feature | ThreatWatch | fastmcp-threatintel |
|---------|-------------|----------------------|
| Real-time watch-list & alerts | ✅ | ❌ |
| Persistent alert history | ✅ | ❌ |
| Shodan InternetDB (free, no key needed) | ✅ | ❌ |
| Status-change detection | ✅ | ❌ |
| IOC extraction from freeform text | ✅ | ❌ |
| Works with zero API keys | ✅ | ❌ |

---

## 🔌 Available MCP Tools

| Tool | Description |
|------|-------------|
| `analyze_ioc` | Analyse a single IP / domain / URL / hash |
| `bulk_analyze` | Analyse up to 50 IOCs concurrently |
| `detect_iocs_in_text` | Extract IOCs from log files, reports, pastes |
| `add_watch` | Add an IOC to the real-time watch-list |
| `remove_watch` | Remove an IOC from the watch-list |
| `list_watches` | Show all monitored IOCs and their status |
| `get_alerts` | Retrieve alerts from monitored IOCs |
| `run_monitor_cycle` | Manually trigger a re-scan of all watches |
| `server_status` | Show configured sources and monitor state |

---

## 🚀 Installation

### Prerequisites
- Python 3.11 or higher
- [Claude Desktop](https://claude.ai/download)
- API keys (see below — all free tier)

### Step 1 — Clone the repo

```bash
git clone https://github.com/YOUR_USERNAME/threatwatch-mcp.git
cd threatwatch-mcp
```

### Step 2 — Install

```bash
pip3 install fastmcp httpx python-dotenv
pip3 install -e .
```

### Step 3 — Verify installation

```bash
which threatwatch
```

You should see a path like `/usr/local/bin/threatwatch` or
`/Library/Frameworks/Python.framework/Versions/3.x/bin/threatwatch`.
Copy this path — you'll need it in Step 5.

---

## 🔑 API Keys (All Free)

| Source | Required | Free Limit | Sign Up |
|--------|----------|------------|---------|
| VirusTotal | Recommended | 1,000 req/day | [virustotal.com](https://www.virustotal.com/gui/join-us) |
| AlienVault OTX | Recommended | Unlimited | [otx.alienvault.com](https://otx.alienvault.com) |
| AbuseIPDB | Optional | 1,000 req/day | [abuseipdb.com](https://www.abuseipdb.com/register) |
| IPinfo | Optional | 50,000 req/month | [ipinfo.io](https://ipinfo.io/signup) |
| **Shodan InternetDB** | **None needed** | **Always free** | Built-in |

> ThreatWatch works with **zero API keys** — Shodan InternetDB is always available
> and returns open ports, CVEs, and hostnames for any IP for free.

---

## ⚙️ Connect to Claude Desktop

### Step 4 — Open the Claude Desktop config

**macOS:**
```bash
open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json
```

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```

### Step 5 — Add ThreatWatch

Add the `threatwatch` entry to your `mcpServers` block.
Replace the command path with the output of `which threatwatch` from Step 3,
and fill in your API keys:

```json
{
  "mcpServers": {
    "threatwatch": {
      "command": "/Library/Frameworks/Python.framework/Versions/3.13/bin/threatwatch",
      "env": {
        "VIRUSTOTAL_API_KEY": "your_virustotal_key_here",
        "OTX_API_KEY": "your_otx_key_here",
        "ABUSEIPDB_API_KEY": "your_abuseipdb_key_here",
        "IPINFO_API_KEY": "your_ipinfo_key_here"
      }
    }
  }
}
```

> If you already have other MCP servers configured, just add the `threatwatch`
> block inside your existing `mcpServers` object — don't replace the whole file.

### Step 6 — Restart Claude Desktop

Fully quit Claude Desktop (`Cmd + Q` on Mac, system tray → Exit on Windows)
and reopen it.

### Step 7 — Verify

Click the **"+"** button at the bottom of the Claude chat → **Connectors**.
You should see ThreatWatch listed with all 9 tools.

Then test it:
```
Run server_status
```

---

## 💬 Example Prompts

```
Analyse IP 185.220.101.1 for threats

Check if domain update-adobe-flash.ru is malicious

Is this hash dangerous: d41d8cd98f00b204e9800998ecf8427e

Extract all IOCs from this log and analyse them:
[paste your firewall log, SIEM alert, or email header]

Add a watch on 185.220.101.1 and alert me if it becomes malicious

Get all alerts from the last hour

Run a full monitor cycle now
```

---

## 🔔 How Real-Time Monitoring Works

```
add_watch("185.220.101.1", alert_on=["malicious", "suspicious"])
         │
         ▼
   Watch-list saved to ~/.threatwatch/watchlist.json
         │
         ▼
run_monitor_cycle()   ← trigger manually or on a schedule
         │
         ▼
   Re-queries all sources for each watched IOC
         │
         ▼
   Status changed or threshold crossed?
         │
    Yes  │  No
    ▼    ▼
  Alert  (no-op)
    │
    ▼
get_alerts(since_minutes=60)
```

---

## 🏗️ Project Structure

```
threatwatch-mcp/
├── src/
│   └── threatwatch/
│       ├── __init__.py        ← package definition
│       ├── server.py          ← FastMCP server + all 9 MCP tools
│       ├── config.py          ← settings from environment variables
│       ├── ioc_detector.py    ← IOC type detection (IP/domain/URL/hash)
│       ├── intel_sources.py   ← API adapters (VT, OTX, AbuseIPDB, IPinfo, Shodan)
│       ├── alert_monitor.py   ← real-time watch-list + alert engine
│       └── reporter.py        ← Markdown report builder
├── tests/
│   └── test_core.py           ← unit tests
├── pyproject.toml             ← package config + dependencies
├── .env.example               ← environment variable template
└── README.md
```

---

## 🔒 Security Notes

- **Never commit your `.env` file** — it is in `.gitignore` by default
- **Restrict config file permissions** on your machine:
  ```bash
  chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
  ```
- All API keys used are **read-only** — they can query data but cannot modify anything
- If a key is ever leaked, regenerate it instantly from each service's dashboard

---

## 🧪 Running Tests

```bash
pip3 install pytest pytest-asyncio
pytest tests/ -v
```

---

## 📜 License

Apache 2.0 — see [LICENSE](LICENSE) for details.

---

## 🙏 Acknowledgments

- [FastMCP](https://github.com/jlowin/fastmcp) — the MCP framework that powers ThreatWatch
- [fastmcp-threatintel](https://github.com/4R9UN/fastmcp-threatintel) — original inspiration
- [VirusTotal](https://www.virustotal.com), [AlienVault OTX](https://otx.alienvault.com),
  [AbuseIPDB](https://www.abuseipdb.com), [IPinfo](https://ipinfo.io),
  [Shodan](https://www.shodan.io) — threat intelligence sources