MCP AbuseIPDB Server

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.

Features

• 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

Quick Start

Prerequisites

• Python 3.11 or higher

• AbuseIPDB API key (get one at abuseipdb.com)

Installation

1. Clone the repository:

2. Install the package:

3. Set up your environment:

4. Run the server:

MCP Client Configuration

Option 1: Using the Enhanced Startup Script (Recommended)

Add to your MCP client configuration (e.g., mcp.json):

Option 2: Direct Module Execution

Important Notes:

• Replace your_api_key_here with your actual AbuseIPDB API key

• Update /path/to/AbuseIPDB-MCP to 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

Available Tools

check_ip

Check the reputation of a single IP address.

Parameters:

• ip_address (required): IP address to check

• max_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_block

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)

get_blacklist

Retrieve the AbuseIPDB blacklist.

Parameters:

• confidence_minimum (optional): Minimum confidence level (default: 90)

• limit (optional): Maximum entries to retrieve

bulk_check

Check multiple IP addresses efficiently.

Parameters:

• ip_addresses (required): List of IP addresses

• max_age_days (optional): Maximum age of reports (default: 30)

• threshold (optional): Confidence threshold for flagging (default: 75)

enrich_log_line

Extract and analyze IP addresses from log entries.

Parameters:

• log_line (required): Log line containing IP addresses

• threshold (optional): Confidence threshold for flagging (default: 75)

• max_age_days (optional): Maximum age of reports (default: 30)

Available Resources

cache://info

Get current cache statistics and rate limiter status.

doc://usage

Complete API usage documentation and examples.

Available Prompts

triage_ip

Generate security analyst triage notes for an IP address.

Parameters:

• ip_data (required): IP check data from AbuseIPDB

Configuration

All configuration is done via environment variables. Copy .env.example to .env and customize:

Required Settings

• ABUSEIPDB_API_KEY: Your AbuseIPDB API key

Optional Settings

• 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)

Usage Examples

Basic IP Check

Log Analysis

Bulk Analysis

Security Investigation

See examples/queries.md for more detailed examples.

Docker Deployment

Build and run with Docker:

Development

Setup Development Environment

Run Tests

Security Considerations

• 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

Rate Limits

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

Troubleshooting

"Unauthorized API key" Error in Claude App

If you're getting unauthorized API key errors when using the MCP server with Claude:

1. Verify API Key Configuration:

   # Test your API key with the diagnostic script python diagnostics/api_auth_diagnostic.py

2. Check Claude App Configuration:

   • Ensure your mcp.json has the correct API key in the env section

   • Verify the cwd path points to your project directory

   • Make sure the API key value matches exactly (no extra spaces)

3. 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

4. Environment Variable Issues:

   • Ensure your .env file is in the project root directory

   • Verify the API key in .env matches your Claude app configuration

   • Check that the API key is valid on the AbuseIPDB website

5. 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))"

Common Issues

• "No .env file found": Make sure .env exists 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

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes with tests

4. Run the test suite and linting

5. Submit a pull request

License

MIT License — see LICENSE for details.

Support

• Documentation: See examples/ directory

• Issues: Please report bugs and feature requests via GitHub issues

• API Documentation: AbuseIPDB API Docs

Changelog

v0.1.0

• Initial release

• Basic IP checking functionality

• CIDR block analysis

• Blacklist access

• Bulk operations

• Log enrichment

• Caching and rate limiting

• Docker support