AbuseIPDB MCP

AbuseIPDB MCP is our first-party Model Context Protocol server. It lets an AI assistant such as Claude, Cursor, VS Code Copilot, or Codex look up IP reputation directly from AbuseIPDB while you work, instead of you copying addresses into a browser tab.

Jump to setup View on GitHub

Status: beta · stdio transport · read-only.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets an AI assistant call external tools in a structured way. An MCP server is a small program that advertises a set of tools; an MCP client is the application you already use — Claude Desktop, Claude Code, Cursor, VS Code with GitHub Copilot, or Codex.

You do not run AbuseIPDB MCP yourself. Your client launches it when it needs it, passes it your AbuseIPDB API key, and talks to it over standard input and output. When the assistant needs to know whether an IP address is malicious, it calls one of the server's tools and gets structured data back.

The server is read-only. It only looks IP addresses up. It cannot submit reports, and it cannot fetch blacklists. Lookups consume your API quota, but do not submit or change abuse reports.

Why use it?

• No tab switching: ask about an IP address inside the tool you are already working in.
• No manual lookup: the assistant pulls confidence score, report count, country, ISP, usage type, and domain in one call.
• Bulk triage: paste a list of addresses and check them with one tool call. The server makes a separate AbuseIPDB API request for each unique, valid address.
• Log investigation: hand the assistant a log excerpt and let it extract and check the addresses it finds.
• Plain-English summaries: every result includes a risk tier and a short summary alongside the raw fields.

Before you start

1. An AbuseIPDB API key. Create one for free on your API settings page.
2. Python 3.11 or newer.
3. uv, which provides the uvx command. Every example below uses uvx, which downloads and runs the server on demand. There is nothing to install first.

Your MCP client starts the server for you. To check that it can start from a macOS or Linux terminal first, run:

ABUSEIPDB_API_KEY=your_key_here uvx mcp-server-abuseipdb

For Windows PowerShell:

$env:ABUSEIPDB_API_KEY = "your_key_here"
    uvx mcp-server-abuseipdb

The server waits for MCP input, so an idle terminal is expected. Starting it checks that a key is present, but does not validate the key against AbuseIPDB. Press Ctrl+C to stop it, then configure your client below and make a lookup to verify the connection.

Quick start

Pick the section that matches your client, save the configuration, then restart or reload the client. The package on PyPI is mcp-server-abuseipdb. If your configuration already contains other servers, add the abuseipdb entry alongside them.

Claude, Cursor, and other mcpServers clients

Most MCP clients accept a top-level mcpServers object. That includes Claude Desktop (Settings → Developer → Edit Config), Claude Code (.mcp.json in your project root), and Cursor (.cursor/mcp.json for one project, ~/.cursor/mcp.json for all of them).

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

In Cursor, also add "type": "stdio" inside the abuseipdb entry. Restart Claude Desktop after saving, or reload the MCP server in your editor.

For shared project files, reference an environment variable instead of committing a key. The syntax differs by client:

• Claude Code: use "ABUSEIPDB_API_KEY": "${ABUSEIPDB_API_KEY}".
• Cursor: use "ABUSEIPDB_API_KEY": "${env:ABUSEIPDB_API_KEY}".

Set the variable in the environment that launches the client before starting it. Keep Claude Desktop's configuration private; do not assume it supports the same variable substitution.

VS Code with GitHub Copilot

Save this as .vscode/mcp.json in your workspace. For a user-level setup, run MCP: Open User Configuration from the Command Palette. VS Code prompts you for the key rather than storing it in the file:

{
  "inputs": [
    {
      "id": "abuseipdb-api-key",
      "type": "promptString",
      "description": "AbuseIPDB API key",
      "password": true
    }
  ],
  "servers": {
    "abuseipdb": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-abuseipdb"],
      "env": {
        "ABUSEIPDB_API_KEY": "${input:abuseipdb-api-key}"
      }
    }
  }
}

Run MCP: List Servers to start, restart, or inspect the server.

Codex

Add this to ~/.codex/config.toml for all projects, or to .codex/config.toml inside a trusted project:

[mcp_servers.abuseipdb]
command = "uvx"
args = ["mcp-server-abuseipdb"]

[mcp_servers.abuseipdb.env]
ABUSEIPDB_API_KEY = "your_key_here"

Restart Codex after saving. For a project configuration you intend to commit, omit the [mcp_servers.abuseipdb.env] block and add env_vars = ["ABUSEIPDB_API_KEY"] under [mcp_servers.abuseipdb] instead. Set the variable before starting Codex. See the Codex MCP documentation.

Example prompts

Once the server is connected, confirm that your client lists check_ip and bulk_check, then ask in plain language. Approve the tool call if your client prompts you. A successful lookup verifies that your API key works; an authentication error means the key needs checking on your API settings page.

Single IP check

• “Check 118.25.6.39 on AbuseIPDB.”
• “Is 1.2.3.4 malicious? Use the last 90 days of reports.”
• “What ISP and country does 8.8.8.8 belong to, and has it been reported?”

Bulk check

• “Check all of these against AbuseIPDB and tell me which ones are risky: 1.2.3.4, 5.6.7.8, 9.10.11.12.”
• “Here are the top 20 source IPs from my firewall export. Rank them by abuse confidence score.”

Log investigation

• “Pull the source IPs out of this SSH auth log, check them on AbuseIPDB, and summarise anything scoring above 50.”
• “These addresses hit my login endpoint overnight. Which are known brute-force sources?”

Tool reference

check_ip

Checks one public IP address.

Returns the abuse confidence score, a risk tier, report metadata, source fields such as country, ISP, usage type and domain, and a short plain-English message.

bulk_check

Checks a list of public IP addresses.

Duplicate addresses are removed before the lookup. Invalid addresses come back as per-item errors rather than failing the whole call. If AbuseIPDB rate-limits one item, the remaining items in that same call are marked skipped instead of being burned against an exhausted quota.

Limits and safety

• A score of 0 is not proof an IP is safe. Review the report count and available report details as well as the score. max_age_in_days controls the report window; it does not recalculate the abuse confidence score for that window.
• Each API lookup uses your check quota. A bulk_check that checks 100 unique, valid addresses makes 100 API requests. Duplicates, locally rejected inputs, and items skipped after a rate limit do not trigger additional requests. AbuseIPDB determines the quota; the server does not cache or predict whether a later request will be allowed.
• Rate limits surface as errors, not silence. An HTTP 429 comes back as a structured RATE_LIMITED error, and a later call works again as soon as your quota allows. When your remaining quota drops to 10% or less of your plan limit, results carry a notice.
• Public addresses only. Hostnames, URLs, CIDR ranges, and private or reserved addresses are rejected by default.
• Keep your key out of source control. Use a private client configuration, your client's environment-variable syntax, or its secret prompt. An env block containing a literal key is still a secret and must not be committed. Never place the key in args. The server reads the key from the environment and does not return it in tool output.

Links

• Source on GitHub
• mcp-server-abuseipdb on PyPI
• MCP Registry (io.github.abuseipdb/abuseipdb-mcp)
• Get an AbuseIPDB API key