AbuseIPDB

You can run an MCP server that integrates with AbuseIPDB to check IP abuse reports and submit abuse reports. This server exposes two core actions you can call from MCP clients: check the reputation of a given IP and report abusive activity, with robust validation, verbose output, and MCP SDK compatibility.

How to use

Use this server from an MCP client to perform two primary actions: check_ip to query AbuseIPDB for reports on a specific IP, and report_ip to submit new abuse reports. You get structured, readable results suitable for automated processing, with detailed category mappings and helpful error messages for rate limits and invalid inputs. To start, ensure your MCP client is configured to target the local stdio server you run, or point it to a remote MCP endpoint if you deploy it elsewhere.

How to install

Prerequisites you need before installing include Python 3.8 or higher, Docker if you plan to use containerized deployment, and an AbuseIPDB API key.

# Prerequisites check (example)
python3 --version
docker --version

Local installation steps are shown here. Follow them in order to set up and run the MCP server on your machine.

# 1) Create a project directory and navigate into it
mkdir abuseipdb-mcp && cd abuseipdb-mcp

# 2) Set up a Python virtual environment
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# or
venv\Scripts\activate     # Windows

# 3) Install dependencies
pip install -r requirements.txt

# 4) Set your AbuseIPDB API key (use your real key in place of the placeholder)
export ABUSEIPDB_API_KEY="YOUR_API_KEY"

# 5) Run the MCP server locally
python src/server.py

Additional configuration and usage notes

The server is designed to work with MCP SDK 1.12.2+ and uses an asynchronous, clean architecture with robust input validation. It includes a complete mapping of abuse categories and returns results in a format friendly to MCP clients, with verbose output enabled by default to provide detailed context for investigations.

If you prefer containerized deployment, you can build and run a Docker image. The container expects the ABUSEIPDB_API_KEY environment variable to be set.

Security and environment considerations

Keep your AbuseIPDB API key secret. Do not commit it to version control. Use environment variables or secret management in production deployments.

The server validates IP formats and handles rate limit responses with clear retry guidance. Monitor logs to identify and respond to authentication issues or network problems.

Running in Docker

To run the server in Docker, build the image and start a container with your API key.

# Build the image
docker build -t abuseipdb-mcp .

# Run with your API key
docker run -it --rm -e ABUSEIPDB_API_KEY="YOUR_API_KEY" abuseipdb-mcp

Docker Compose

version: '3.8'
services:
  abuseipdb-mcp:
    build: .
    environment:
      - ABUSEIPDB_API_KEY=YOUR_API_KEY
    stdin_open: true
    tty: true
    restart: unless-stopped

MCP client integration (examples)

Configure your MCP client to connect to this server using the standard MCP connection pattern. The server exposes two tools you can call from the client: check_ip and report_ip, each returning structured results suitable for display or automation.

Notes on output and compatibility

The server aims for clean, readable output without markdown formatting and is compatible with MCP SDK 1.12.2+. It provides verbose results by default to help with analysis and triage.

Available tools

check_ip

Check an IP address for abuse reports and return verbose results including categories, country, ISP, and recent reports.

report_ip

Submit an abuse report for a specific IP address with selected categories and optional comment and timestamp.