An MCP (Model Context Protocol) server that provides threat intelligence lookups against the AbuseIPDB database. This server enables any MCP-capable client to perform IP reputation checks, CIDR block analysis, and access curated blacklists with intelligent caching and rate limiting.
- IP Reputation Checks: Single IP address lookups with detailed abuse data
- CIDR Block Analysis: Check entire network ranges for malicious activity
- Blacklist Access: Retrieve current AbuseIPDB blacklist with configurable confidence levels
- Bulk Operations: Check multiple IP addresses efficiently
- Log Enrichment: Extract and analyze IP addresses from log lines
- Intelligent Caching: SQLite-based caching with TTL to minimize API usage
- Rate Limiting: Built-in quota management for AbuseIPDB API limits
- Security Focused: Input validation, private IP filtering, and secure defaults
- Python 3.11 or higher
- AbuseIPDB API key (get one at abuseipdb.com)
- Clone the repository:
git clone <repository-url>
cd AbuseIPDB-MCP- Install the package:
pip install -e .- Set up your environment:
cp .env.example .env
# Edit .env and add your ABUSEIPDB_API_KEY- Run the server:
python -m mcp_abuseipdb.serverAdd to your MCP client configuration (e.g., mcp.json):
{
"mcpServers": {
"mcp-abuseipdb": {
"command": "python",
"args": ["scripts/start_mcp_server.py"],
"cwd": "/path/to/AbuseIPDB-MCP",
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}{
"mcpServers": {
"mcp-abuseipdb": {
"command": "python",
"args": ["-m", "mcp_abuseipdb.server"],
"cwd": "/path/to/AbuseIPDB-MCP",
"env": {
"ABUSEIPDB_API_KEY": "your_api_key_here"
}
}
}
}Important Notes:
- Replace
your_api_key_herewith your actual AbuseIPDB API key - Update
/path/to/AbuseIPDB-MCPto the actual path where you cloned this repository - The enhanced startup script (Option 1) provides better error diagnostics
- Ensure your API key is valid and not expired on the AbuseIPDB website
Check the reputation of a single IP address.
Parameters:
ip_address(required): IP address to checkmax_age_days(optional): Maximum age of reports (default: 30)verbose(optional): Include detailed reports (default: false)threshold(optional): Confidence threshold for flagging (default: 75)
Check the reputation of a CIDR network block.
Parameters:
network(required): CIDR network (e.g., "192.168.1.0/24")max_age_days(optional): Maximum age of reports (default: 30)
Retrieve the AbuseIPDB blacklist.
Parameters:
confidence_minimum(optional): Minimum confidence level (default: 90)limit(optional): Maximum entries to retrieve
Check multiple IP addresses efficiently.
Parameters:
ip_addresses(required): List of IP addressesmax_age_days(optional): Maximum age of reports (default: 30)threshold(optional): Confidence threshold for flagging (default: 75)
Extract and analyze IP addresses from log entries.
Parameters:
log_line(required): Log line containing IP addressesthreshold(optional): Confidence threshold for flagging (default: 75)max_age_days(optional): Maximum age of reports (default: 30)
Get current cache statistics and rate limiter status.
Complete API usage documentation and examples.
Generate security analyst triage notes for an IP address.
Parameters:
ip_data(required): IP check data from AbuseIPDB
All configuration is done via environment variables. Copy .env.example to .env and customize:
ABUSEIPDB_API_KEY: Your AbuseIPDB API key
MAX_AGE_DAYS: Default report age limit (default: 30)CONFIDENCE_THRESHOLD: Default confidence threshold (default: 75)DAILY_QUOTA: API request quota (default: 1000)CACHE_DB_PATH: SQLite cache file location (default: ./cache.db)LOG_LEVEL: Logging level (default: INFO)ALLOW_PRIVATE_IPS: Allow checking private IPs (default: false)
Check the reputation of 8.8.8.8
Analyze this log line for threats:
192.168.1.100 - - [10/Jan/2024:10:00:00 +0000] "GET /admin/login.php HTTP/1.1" 200 1234
Check these IPs for malicious activity:
- 203.0.113.100
- 198.51.100.50
- 192.0.2.25
I'm investigating suspicious activity from 203.0.113.100. Can you:
1. Check its reputation with detailed reports
2. Analyze the surrounding network block
3. Generate triage notes for our security team
See examples/queries.md for more detailed examples.
Build and run with Docker:
# Build the image
docker build -f docker/Dockerfile -t mcp-abuseipdb .
# Run the container
docker run -e ABUSEIPDB_API_KEY=your_key_here mcp-abuseipdbpip install -e ".[dev]"
pre-commit installpytest- API Key Protection: Never commit API keys to version control
- Private IP Filtering: Private IPs are blocked by default
- Rate Limiting: Built-in quota management prevents API abuse
- Input Validation: All inputs are validated and sanitized
- Caching: Reduces API calls and improves performance
AbuseIPDB free tier provides 1,000 requests per day. This server:
- Implements intelligent caching to minimize API usage
- Provides rate limiting with configurable quotas
- Gracefully handles rate limit errors with backoff
If you're getting unauthorized API key errors when using the MCP server with Claude:
-
Verify API Key Configuration:
# Test your API key with the diagnostic script python diagnostics/api_auth_diagnostic.py -
Check Claude App Configuration:
- Ensure your
mcp.jsonhas the correct API key in theenvsection - Verify the
cwdpath points to your project directory - Make sure the API key value matches exactly (no extra spaces)
- Ensure your
-
Use Enhanced Startup Script:
- Switch to Option 1 configuration (enhanced startup script)
- Check the server logs in Claude app for diagnostic messages
- Look for
[MCP AbuseIPDB]prefixed messages
-
Environment Variable Issues:
- Ensure your
.envfile is in the project root directory - Verify the API key in
.envmatches your Claude app configuration - Check that the API key is valid on the AbuseIPDB website
- Ensure your
-
Debug Steps:
# Test local server startup python scripts/start_mcp_server.py # Check environment loading python -c "from mcp_abuseipdb.settings import Settings; print('API key loaded:', bool(Settings().abuseipdb_api_key))"
- "No .env file found": Make sure
.envexists in project root or set API key in Claude app config - "Settings API key: EMPTY": API key not properly loaded from environment
- "Environment var: EMPTY": API key not set in Claude app MCP configuration
- Connection timeouts: Check your internet connection and AbuseIPDB service status
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Run the test suite and linting
- Submit a pull request
MIT License — see LICENSE for details.
- Documentation: See
examples/directory - Issues: Please report bugs and feature requests via GitHub issues
- API Documentation: AbuseIPDB API Docs
- Initial release
- Basic IP checking functionality
- CIDR block analysis
- Blacklist access
- Bulk operations
- Log enrichment
- Caching and rate limiting
- Docker support