Set your AbuseIPDB API key as an environment variable:

export ABUSEIPDB_API_KEY="your_api_key_here"

Running the Server

python src/server.py

MCP Configuration

This server includes a complete MCP configuration file (mcp.json) that defines:

Server metadata: Name, version, description, and author information
Tool definitions: Complete parameter schemas with validation patterns
Environment variables: Required API key configuration
Rate limits: Documentation of AbuseIPDB API limits by subscription tier
Usage examples: Practical examples for each tool
Category reference: Complete list of AbuseIPDB abuse categories

Using with MCP Clients

Copy the server configuration to your MCP client's configuration:

{
  "mcpServers": {
    "abuseipdb-python": {
      "command": "python",
      "args": ["path/to/abuseipdb-mcp-server/src/server.py"],
      "env": {
        "ABUSEIPDB_API_KEY": "your_api_key_here"
      }
    }
  }
}

Test the server:
```
python test/test_server.py
```

MCP Tools Available

The server exposes two tools to MCP clients:

`check_ip`

Purpose: Check IP reputation and abuse reports
Parameters: ipAddress (required), maxAgeInDays (optional), verbose (optional)
Returns: Formatted abuse report with confidence score, geolocation, and recent reports

`report_ip`

Purpose: Report abusive IP addresses
Parameters: ip (required), categories (required), comment (optional), timestamp (optional)
Returns: Confirmation with updated abuse confidence score

Docker Deployment

Quick Start with Docker

Set your API key:

# Linux/macOS
export ABUSEIPDB_API_KEY="your_api_key_here"

# Windows
set ABUSEIPDB_API_KEY=your_api_key_here

Build and run:

docker build -t abuseipdb-mcp .
docker run -it --rm \
  --name abuseipdb-mcp \
  -e ABUSEIPDB_API_KEY="your_api_key_here" \
  abuseipdb-mcp

Docker Compose

Create a .env file:

echo "ABUSEIPDB_API_KEY=your_api_key_here" > .env

Start with Docker Compose:
```
docker-compose up --build
```
Stop the service:
```
docker-compose down
```

Docker Features

Ultra-lightweight: Uses Python 3.11 Alpine base image for minimal size (~50MB)
Secure: Runs as non-root user with restricted permissions
Fast builds: Alpine's small footprint reduces build and deployment times
Environment validation: Validates API key on startup
Cross-platform: Works on Linux, macOS, and Windows
Production ready: Optimized for containerized deployments

Claude Desktop Integration

For Claude Desktop, add this to your configuration file:

Location: ~/Library/

Categories

Current Category: abuseipdb-api

mcp-abuseipdb