mcp-server-abuseipdb 0.1.0

Official AbuseIPDB MCP server — check IP reputation from MCP clients

AbuseIPDB MCP

AbuseIPDB MCP is a small Model Context Protocol server for checking IP reputation from MCP clients such as Claude, Cursor, VS Code, Codex, and others. It talks to the AbuseIPDB API v2 over HTTPS and exposes the results as MCP tools over stdio.

Current server status: stdio, read-only. Published on PyPI as mcp-server-abuseipdb, on Docker Hub as abuseipdb/abuseipdb-mcp, and in the MCP Registry as io.github.abuseipdb/abuseipdb-mcp.

What it does

• Checks one public IPv4 or IPv6 address with check_ip.
• Checks a batch of public IPs with bulk_check (cap configurable, default 100).
• Returns AbuseIPDB confidence score, report count, country, ISP, usage type, domain, last report time, risk tier, and a short plain-English summary.
• Rejects hostnames, URLs, CIDR ranges, and private/reserved addresses by default.
• Returns structured errors for bad input, auth failures, timeouts, rate limits, and AbuseIPDB API errors.
• Publishes MCP tool annotations for read-only, idempotent, open-world calls.

It does not submit reports or fetch blacklists yet.

Requirements

• Python 3.11+
• uv
• An AbuseIPDB API key

Install

The distribution on PyPI is mcp-server-abuseipdb; the command it installs is abuseipdb-mcp. Most users do not need to install anything ahead of time — uvx fetches and runs it on demand, which is the form every client example below uses.

Run it once by hand to confirm your key works:

ABUSEIPDB_API_KEY=your_key_here uvx mcp-server-abuseipdb

To keep a persistent install on PATH instead:

uv tool install mcp-server-abuseipdb

The server uses MCP stdio. It waits for JSON-RPC on stdin and looks idle when started from a terminal; that is expected. Stdout is reserved for JSON-RPC messages, so logs go to stderr.

MCP client setup

Most MCP clients use this shape:

{
  "mcpServers": {
    "abuseipdb": {
      "command": "uvx",
      "args": ["mcp-server-abuseipdb"],
      "env": {
        "ABUSEIPDB_API_KEY": "your_key_here"
      }
    }
  }
}

Checked-in examples:

• examples/mcp/mcpServers.json for Claude Desktop, Claude Code, Cursor, and other mcpServers clients
• examples/mcp/codex-config.toml for Codex CLI and Codex desktop
• examples/mcp/vscode-copilot-mcp.json for VS Code Copilot (uses servers, not mcpServers, and prompts for the key instead of storing it)
• examples/mcp/claude-code-project.mcp.json for a Claude Code project config
• examples/mcp/docker.json for running the published image instead of uvx

Keep the key in env, an envFile, or your client secret store. Do not put it in args and do not commit real keys.

Tools

check_ip

Checks one public IP address.

Parameter	Default	Notes
ip	required	Public IPv4 or IPv6 address
max_age_in_days	30	AbuseIPDB report window, 1-365
verbose	true	Include AbuseIPDB report details when available

Returns a normalized dict with abuseConfidenceScore, riskTier, report metadata, source fields, and message.

bulk_check

Checks a list of public IP addresses.

Parameter	Default	Notes
ips	required	IPv4/IPv6 addresses; cap set by ABUSEIPDB_MAX_BULK_IPS (default 100)
max_age_in_days	30	AbuseIPDB report window, 1-365

Duplicate inputs are deduplicated. Invalid IPs are returned as per-item errors. If AbuseIPDB rate-limits an item, the remaining items in that same call are marked skipped rather than burned against an exhausted quota.

Rate limits

AbuseIPDB is the sole authority on your quota. This server does not cache or predict limit state across requests:

• An HTTP 429 is returned to the caller as a structured RATE_LIMITED error.
• The short-circuit is scoped to a single bulk_check call. A later tool invocation contacts AbuseIPDB again, so a retry works as soon as your quota allows.
• When a response shows the remaining quota at or below 10% of your plan limit, the result carries a notice field.

Environment

Variable	Default	Purpose
ABUSEIPDB_API_KEY	required	AbuseIPDB API key
ABUSEIPDB_ALLOW_PRIVATE	false	Allow private/reserved IPs for lab use
ABUSEIPDB_REQUEST_TIMEOUT	30	API timeout in seconds
ABUSEIPDB_API_BASE_URL	AbuseIPDB v2 URL	Override for tests, proxies, or a local backend
ABUSEIPDB_MAX_BULK_IPS	100	Max IPs accepted per bulk_check call
ABUSEIPDB_ENABLE_WRITE_TOOLS	false	Reserved gate for future write tools

Docker

docker run --rm -i -e ABUSEIPDB_API_KEY=your_key_here abuseipdb/abuseipdb-mcp:0.1.0

As an MCP client entry, note that -i is required — the server speaks stdio:

{
  "mcpServers": {
    "abuseipdb": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ABUSEIPDB_API_KEY",
        "abuseipdb/abuseipdb-mcp:0.1.0"
      ],
      "env": { "ABUSEIPDB_API_KEY": "your_key_here" }
    }
  }
}

To build locally instead:

docker build -t abuseipdb-mcp:local .

Development

git clone https://github.com/AbuseIPDB/abuseipdb-mcp.git
cd abuseipdb-mcp
uv sync
cp .env.example .env   # then set ABUSEIPDB_API_KEY

Run the server from the checkout (--env-file loads .env; uv run alone does not):

uv run --env-file .env abuseipdb-mcp

Tests and lint:

uv run pytest -q
uv run ruff check .

Protocol validation runs through the development npm package. MCP Inspector is interactive; the conformance suite is scriptable and runs in CI:

npm install
npm run mcp:inspector     # interactive UI
npm run mcp:conformance   # automated protocol compliance

Coming next

• check_block for CIDR lookups through AbuseIPDB /check-block.
• report_ip, hidden unless ABUSEIPDB_ENABLE_WRITE_TOOLS=true.
• Bounded concurrency and compact flagged-only output for bulk_check.
• Optional hosted Streamable HTTP transport for team or remote use.

Release process for maintainers: see RELEASING.md.

Safety notes

• This server is read-only today.
• An abuse score of 0 means no reports in the selected window, not proof that an IP is safe.
• AbuseIPDB quotas depend on your account. bulk_check consumes one lookup per checked IP.
• Secrets are read from the environment and are not returned in tool output.

License

MIT. See LICENSE.