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:

git clone <repository-url>
cd AbuseIPDB-MCP

2. Install the package:

pip install -e .

3. Set up your environment:

cp .env.example .env
# Edit .env and add your ABUSEIPDB_API_KEY

4. Run the server:

python -m mcp_abuseipdb.server

MCP Client Configuration

Option 1: Using the Enhanced Startup Script (Recommended)

Add 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"
      }
    }
  }
}

Option 2: Direct Module Execution

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

Check the reputation of 8.8.8.8

Log Analysis

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

Bulk Analysis

Check these IPs for malicious activity:
- 203.0.113.100
- 198.51.100.50
- 192.0.2.25

Security Investigation

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.

Docker Deployment

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-abuseipdb

Development

Setup Development Environment

pip install -e ".[dev]"
pre-commit install

Run Tests

pytest

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