sec-mcp

<!-- mcp-name: io.github.montimage/sec-mcp -->

Check domains, URLs and IP addresses against live security blacklists — as a Python library, a terminal CLI, or an MCP server that gives LLM agents real-time threat context.

<p align="left"> <a href="https://github.com/Montimage/sec-mcp/actions/workflows/ci.yml"><img src="https://github.com/Montimage/sec-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://pypi.org/project/sec-mcp/"><img src="https://img.shields.io/pypi/v/sec-mcp.svg?label=PyPI&color=blue" alt="PyPI"></a> <a href="https://pypi.org/project/sec-mcp/"><img src="https://img.shields.io/pypi/pyversions/sec-mcp.svg?label=Python&color=informational" alt="Python Versions"></a> <a href="https://pepy.tech/projects/sec-mcp"><img src="https://static.pepy.tech/badge/sec-mcp" alt="PyPI Downloads"></a> <a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="Apache License 2.0"></a> </p>

sec-mcp aggregates ten public threat-intelligence feeds into a local SQLite database and answers "is this domain/URL/IP malicious?" in microseconds. Use it inside any Python application, from the terminal with sec-mcp, or as a Model Context Protocol server so tools like Claude Desktop, Cursor and Windsurf can screen indicators against real blacklist data.

Developed by Montimage, a company specializing in cybersecurity and network monitoring solutions.

---

Table of Contents

• Features
• Demo
• Quick Start
• Installation
• Usage
  • CLI
  • Python API
  • MCP Server
• Performance Optimization
• Benchmarking
• Configuration
• Project Structure
• Documentation
• Contributing
• Related Publications
• License
• Acknowledgments

---

Features

• Comprehensive security checks — validate domains, URLs and IPv4/IPv6 addresses, with domain→URL cascade semantics (a blacklisted domain condemns its URLs and subdomains; a blacklisted URL does not condemn its domain) and CIDR-range matching for IPs
• Ten threat-intelligence feeds — OpenPhish, PhishStats, URLhaus, PhishTank, Spamhaus DROP, Dshield, CINSSCORE, EmergingThreats, FeodoTracker and BlocklistDE
• Three interfaces, one engine — Python API (SecMCP), Click CLI (sec-mcp), and an MCP server (sec-mcp-server, stdio or streamable HTTP) exposing six typed tools
• Two storage backends — default SQLite storage (v1), or an in-memory hybrid (v2, MCP_USE_V2_STORAGE=true) with O(1) per-type indexes; up to ~28,000x faster lookups than the database-only path on the bundled benchmark
• URL normalization — one canonicalizer shared by both backends: lowercasing, default-scheme handling and tracking-parameter stripping (utm_*, fbclid, …), so URL variants share one verdict
• Safe feed ingestion — HTTPS-only downloads bounded by max_feed_bytes and entry-count sanity checks; a failing feed never aborts the others
• Scheduled daily updates — a schedule job refreshes feeds at update_time; forced updates are rate limited to one per min_update_interval_seconds (default 300 s)
• Concurrency-friendly — SQLite in WAL mode with synchronous=NORMAL, a thread-local shared connection per check, and lock-free snapshot reads on the v2 backend
• Structured MCP output — every tool publishes a typed outputSchema, results carry structuredContent, check_batch reports a tri-state verdict (safe / blacklisted / invalid), and domain failures surface as isError results instead of protocol crashes
• Observable — get_diagnostics MCP tool (summary / full / health / performance / sample modes), real scheduler_alive reporting and per-source entry counts

---

Demo

PLACEHOLDER — needs maintainer input before publishing. The repository ships no screenshot or demo assets today. Suggested: an asciinema recording of sec-mcp update → sec-mcp check <url>, or a screenshot of the six MCP tools inside Claude Desktop. Add the file under docs/assets/ (e.g. docs/assets/demo.gif) and replace this block with ![sec-mcp demo](docs/assets/demo.gif).

---

Quick Start

From zero to a verdict in under five minutes:

pip install sec-mcp
sec-mcp update                        # download + index the feeds (first run only)
sec-mcp check https://example.com     # → Status: Safe / Blacklisted
sec-mcp status                        # entry counts + per-source breakdown

To run it as an MCP server instead, jump to MCP Server — no install beyond uvx is needed.

---

Installation

pip install sec-mcp

Requirements

• Python 3.11 or newer (CI tests 3.11–3.14)
• SQLite 3 (bundled with Python)
• Optional: pytricia via pip install "sec-mcp[fast-cidr]" for fast CIDR matching; without it a pure-Python ipaddress matcher is used (pytricia builds from source and needs a C compiler)

From source

Requires uv (pip install uv if needed):

git clone https://github.com/Montimage/sec-mcp.git
cd sec-mcp
uv sync    # creates .venv, installs the package editable + dev tools, pinned by uv.lock

---

Usage

CLI

# Single check — auto-detects domain vs URL vs IP
sec-mcp check https://example.com
sec-mcp check malicious-domain.com
sec-mcp check 192.168.1.1

# Type-specific checks
sec-mcp check-domain example.com
sec-mcp check-url https://example.com/path
sec-mcp check-ip 192.168.1.1

# Batch check from a file (one value per line)
sec-mcp batch urls.txt

# Status, updates, sampling and cache control
sec-mcp status
sec-mcp update
sec-mcp sample -n 20
sec-mcp flush-cache

Every command except sample accepts --json for machine-readable output.

Python API

from sec_mcp import SecMCP

client = SecMCP()          # optional: SecMCP(db_path="/path/to/mcp.db")
client.update()            # download + index the feeds (first run only)

# Single check — check() returns CheckResult(blacklisted, explanation)
result = client.check("https://example.com")
print(result.blacklisted, result.explanation)
# result.to_dict() -> {"is_safe": True, "explain": "Not blacklisted"}

# Type-specific checks
client.check_domain("example.com")
client.check_url("https://example.com/path")
client.check_ip("192.168.1.1")

# Batch check
urls = ["https://example.com", "https://test.com", "192.168.1.1"]
for value, r in zip(urls, client.check_batch(urls)):
    print(f"{value}: {'BLOCKED' if r.blacklisted else 'SAFE'}")

# Status — StatusInfo(entry_count, last_update, sources, server_status)
status = client.get_status()
print(status.entry_count, status.last_update, client.scheduler_alive())

MCP Server

sec-mcp runs as a stdio MCP server for AI/LLM integration (Claude Desktop, Cursor, Windsurf, …). server.json at the repo root ships the matching MCP Registry entry (io.github.montimage/sec-mcp).

1. Install uv (provides uvx): see the uv installation docs, or pip install uv.

2. Populate the blacklist once:

   uvx --from sec-mcp sec-mcp update
   

3. Configure your MCP client (e.g. claude_desktop_config.json):

   {
     "mcpServers": {
       "sec-mcp": {
         "command": "uvx",
         "args": ["--from", "sec-mcp", "sec-mcp-server"],
         "env": { "MCP_USE_V2_STORAGE": "true" }
       }
     }
   }
   

   How it works: uvx downloads the sec-mcp package from PyPI and runs its sec-mcp-server entry point — no virtual environment or absolute Python path required. Alternatively, pip install sec-mcp into any environment and use "command": "sec-mcp-server" with no args.

MCP tools

| Tool | Description | |---------------------|--------------------------------------------------------------------------| | check_batch | Check multiple domains/URLs/IPs in one call | | get_status | Blacklist status: entry counts, per-source breakdown, scheduler_alive | | update_blacklists | Force an immediate update (rate limited; emits per-source progress) | | get_diagnostics | Diagnostic info — modes: summary, full, health, performance, sample | | add_entry | Manually add a blacklist entry (URL/domain or IP, optional score) | | remove_entry | Remove a blacklist entry by domain, URL or IP |

update_blacklists is rate limited to one forced update per min_update_interval_seconds (default 300 in config.json): a second call inside the window returns {"updated": false, "reason": ...} without starting downloads, and callers that supply a progress token receive one notifications/progress per source.

The get_diagnostics modes:

• summary (default): entry counts, sources and last update times
• full: complete diagnostic data including health, stats and performance
• health: database reachability and scheduler state only
• performance: lookup metrics and hit rates (v2 storage only)
• sample: random sample of blacklist entries (sample_count parameter, 1–100)

HTTP transport and the landing-page playground

sec-mcp-server speaks stdio by default. Add --http to serve MCP over streamable HTTP instead, so a browser — including the live playground on the landing page — can call the tools:

sec-mcp update                       # populate the database once
sec-mcp-server --http                # → http://127.0.0.1:8000/mcp
sec-mcp-server --http --host 0.0.0.0 --port 9000

• CORS allows the origins in SEC_MCP_CORS_ORIGINS (default: local Vite dev/preview on ports 3000/4173 and https://montimage.github.io); credentials are never allowed. * allows any origin and also disables DNS-rebinding protection.
• Set SEC_MCP_HTTP_AUTH_TOKEN to require Authorization: Bearer <token> on every request. Binding a non-loopback host (e.g. --host 0.0.0.0) without one generates a random token for that run and prints it with a #token=… fragment: append it to the landing-page URL and the playground connects with it. Pass --no-auth to opt out (a warning is logged).

---

Performance Optimization

Enable the in-memory v2 backend for dramatically faster lookups:

export MCP_USE_V2_STORAGE=true

Measured results

Numbers below come from the bundled harness (run_benchmark.sh, see Benchmarking):

| Operation | v1 (Database) | v0.3.0 (Hybrid) | v0.4.0+ (Optimized) | Speedup (vs v1) | |------------------|---------------|-----------------|---------------------|-----------------| | Domain check | 10 ms | 0.01 ms | 0.006 ms | ~1,600x | | URL check | 5 ms | 0.001 ms | 0.0007 ms | ~7,000x | | IP + CIDR check | 200 ms | 0.01 ms | 0.007 ms | ~28,000x | | Batch 100 items | 2–3 s | 50–100 ms | 50–100 ms | ~30x |

Memory usage

• v1 (default): ~10 MB (database on disk)
• v2: ~40–80 MB in-memory, depending on feed size

How v2 is fast

1. One in-memory index per entry type — O(1) hash lookups over single domain/URL/IP indexes; reload builds a scratch index and swaps it under the lock, so readers never block and always see a complete snapshot.
2. URL normalization — HTTP://EVIL.COM/ → http://evil.com; tracking parameters (utm_*, fbclid, …) str