🛡️ ThreatWatch MCP

AI-Powered Threat Intelligence with Real-Time Alert Monitoring

A Model Context Protocol (MCP) server that brings multi-source threat intelligence directly into Claude Desktop and any MCP-compatible AI assistant.

---

✨ 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
• API keys (see below — all free tier)

Step 1 — Clone the repo

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

Step 2 — Install

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

Step 3 — Verify installation

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
AlienVault OTX	Recommended	Unlimited	otx.alienvault.com
AbuseIPDB	Optional	1,000 req/day	abuseipdb.com
IPinfo	Optional	50,000 req/month	ipinfo.io
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:

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:

{
  "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:

  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

pip3 install pytest pytest-asyncio
pytest tests/ -v

---

📜 License

Apache 2.0 — see LICENSE for details.

---

🙏 Acknowledgments

• FastMCP — the MCP framework that powers ThreatWatch
• fastmcp-threatintel — original inspiration
• VirusTotal, AlienVault OTX, AbuseIPDB, IPinfo, Shodan — threat intelligence sources