README - sec-mcp: Security Checking Toolkit by montimage

sec-mcp: Security Checking Toolkit

A Python toolkit providing security checks for domains, URLs, IPs, and more. Integrate easily into any Python application, use via terminal CLI, or run as an MCP server to enrich LLM context with real-time threat insights.

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

MCP Server & LLM Support

sec-mcp is designed for seamless integration with Model Context Protocol (MCP) compatible clients (e.g., Claude, Windsurf, Cursor) for real-time security checks in LLM workflows.

Available MCP Tools

Tool Name	Signature / Endpoint	Description
`check_blacklist`	`check_blacklist(value: str)`	Check a single value (domain, URL, or IP) against the blacklist.
`check_batch`	`check_batch(values: List[str])`	Bulk check multiple domains/URLs/IPs in one call.
`get_blacklist_status`	`get_blacklist_status()`	Get status of the blacklist, including entry counts and per-source breakdown.
`sample_blacklist`	`sample_blacklist(count: int)`	Return a random sample of blacklist entries.
`get_source_stats`	`get_source_stats()`	Retrieve detailed stats: total entries, per-source counts, last update timestamps.
`get_update_history`	`get_update_history(...)`	Fetch update history records, optionally filtered by source and time range.
`flush_cache`	`flush_cache()`	Clear the in-memory URL/IP cache.
`add_entry`	`add_entry(url, ip, ...)`	Manually add a blacklist entry.
`remove_entry`	`remove_entry(value: str)`	Remove a blacklist entry by URL or IP address.
`update_blacklists`	`update_blacklists()`	Force immediate update of all blacklists.
`health_check`	`health_check()`	Perform a health check of the database and scheduler.

MCP Server Setup

To run sec-mcp as an MCP server for AI-driven clients (e.g., Claude), follow these steps:

Create a virtual environment:
```
python3.12 -m venv .venv
```

Activate the virtual environment:

source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat

Install sec-mcp:
```
pip install sec-mcp
```
Verify the status:
```
sec-mcp status
```
Update the blacklist database:
```
sec-mcp update
```
Verify the database:
```
sec-mcp status
```
Configure your MCP client (e.g., Claude, Windsurf, Cursor) to point at the command:
```
{
  "mcpServers": {
    "sec-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "sec_mcp.start_server"]
    }
  }
}
```
Important:
- Use the absolute path to the Python executable in your virtual environment.
- For Windows, the path might look like: C:\path\to\.venv\Scripts\python.exe
The sec-mcp tools should now be available in your MCP client for checking URLs, domains, and IPs.

API Functions

Function Name	Signature	Description
`check`	`check(value: str) -> CheckResult`	Check a single domain, URL, or IP against the blacklist.
`check_batch`	`check_batch(values: List[str]) -> List[CheckResult]`	Batch check of multiple values.
`check_ip`	`check_ip(ip: str) -> CheckResult`	Check if an IP (or network) is blacklisted.
`check_domain`	`check_domain(domain: str) -> CheckResult`	Check if a domain (including parent domains) is blacklisted.
`check_url`	`check_url(url: str) -> CheckResult`	Check if a URL is blacklisted.
`get_status`	`get_status() -> StatusInfo`	Get current status of the blacklist service.
`update`	`update() -> None`	Force an immediate update of all blacklists.
`sample`	`sample(count: int = 10) -> List[str]`	Return a random sample of blacklist entries.

Features

Comprehensive security checks for domains, URLs, IP addresses, and more against multiple blacklist feeds
On-demand updates from OpenPhish, PhishStats, URLhaus and custom sources
High-performance, thread-safe SQLite storage with in-memory caching for fast lookups
Python API via SecMCP class for easy integration into your applications
Intuitive Click-based CLI for interactive single or batch scans
Built-in MCP server support for LLM/AI integrations over JSON/STDIO

Environment Variable: MCP_DB_PATH

By default, sec-mcp stores its SQLite database (mcp.db) in a shared, cross-platform location:

macOS: ~/Library/Application Support/sec-mcp/mcp.db
Linux: ~/.local/share/sec-mcp/mcp.db
Windows: %APPDATA%\sec-mcp\mcp.db

You can override this location by setting the MCP_DB_PATH environment variable:

export MCP_DB_PATH=/path/to/your/custom/location/mcp.db

Set this variable before running any sec-mcp commands or starting the server. The directory will be created if it does not exist.

Installation

pip install sec-mcp

Usage via CLI

Create and activate a virtual environment (recommended):

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat

Install the package:
```
pip install sec-mcp
```
Verify the status:
```
sec-mcp status
```
Populate the database with security data:
```
sec-mcp update
```
Verify the database has been populated:
```
sec-mcp status
```
Check a single URL/domain/IP:
```
sec-mcp check https://example.com
```
Batch check from a file:
```
sec-mcp batch urls.txt
```

Usage via API (Python)

Create and activate a virtual environment (recommended):

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat

Install in your project:
```
pip install sec-mcp
```

Import, initialize, and update the database:

from sec_mcp import SecMCP

client = SecMCP()

# Populate the database with security data (run once after installation)
client.update()

Single check:

result = client.check("https://example.com")
print(result.to_json())

Batch check:

urls = ["https://example.com", "https://test.com"]
results = client.check_batch(urls)
for r in results:
    print(r.to_json())

Usage via MCP Client

To run sec-mcp as an MCP server for AI-driven clients (e.g., Claude):

Create a virtual environment:
```
python3.12 -m venv .venv
```

Activate the virtual environment:

source .venv/bin/activate  # On Windows: .venv\Scripts\activate.bat

Install sec-mcp:
```
pip install sec-mcp
```
Verify the status:
```
sec-mcp status
```
Update the blacklist database:
```
sec-mcp update
```
Verify the database:
```
sec-mcp status
```
Configure your MCP client (e.g., Claude, Windsurf, Cursor) with:
```
{
  "mcpServers": {
    "sec-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "sec_mcp.start_server"]
    }
  }
}
```
Note:
- Use the absolute path to the Python executable in your virtual environment.
- For Windows, the path might look like: C:\path\to\.venv\Scripts\python.exe
The sec-mcp tools should now be available in your MCP client.

New MCP Server Tools

The following RPC endpoints are now available:

check_batch(values: List[str]): Bulk check multiple domains/URLs/IPs in one call. Returns a list of { value, is_safe, explanation }.
sample_blacklist(count: int): Return a random sample of blacklist entries for quick inspection.
get_source_stats(): Retrieve detailed stats: total entries, per-source counts, and last update timestamps. Returns { total_entries, per_source, last_updates }.
get_update_history(source?: str, start?: str, end?: str): Fetch update history records, optionally filtered by source and time range.
flush_cache(): Clear the in-memory URL/IP cache. Returns { cleared: bool }.
health_check(): Perform a health check of the database and scheduler. Returns { db_ok: bool, scheduler_alive: bool, last_update: timestamp }.
add_entry(url: str, ip?: str, date?: str, score?: float, source?: str): Manually add a blacklist entry. Returns { success: bool }.
remove_entry(value: str): Remove a blacklist entry by URL or IP address. Returns { success: bool }.

Configuration

The client can be configured via config.json:

blacklist_sources: URLs for blacklist feeds
update_time: Daily update schedule (default: "00:00")
cache_size: In-memory cache size (default: 10000)
log_level: Logging verbosity (default: "INFO")

Development

Clone the repository and install in development mode:

git clone <repository-url>
cd sec-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e .

License

MIT

About Montimage

sec-mcp is developed and maintained by Montimage, a company specializing in cybersecurity and network monitoring solutions. Montimage provides innovative security tools and services to help organizations protect their digital assets and ensure the security of their networks.

For questions or support, please contact us at .