Metadata-Version: 2.4
Name: mcp-server-abuseipdb
Version: 0.1.0
Summary: Official AbuseIPDB MCP server — check IP reputation from MCP clients
Keywords: mcp,abuseipdb,security,threat-intelligence,ip-reputation
Author: AbuseIPDB
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp>=1.27.1,<2
Requires-Dist: pydantic>=2.13.4,<3
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/AbuseIPDB/abuseipdb-mcp
Project-URL: Documentation, https://github.com/AbuseIPDB/abuseipdb-mcp#readme
Project-URL: Repository, https://github.com/AbuseIPDB/abuseipdb-mcp
Project-URL: Issues, https://github.com/AbuseIPDB/abuseipdb-mcp/issues
Description-Content-Type: text/markdown

# AbuseIPDB MCP

<!-- mcp-name: io.github.abuseipdb/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](https://registry.modelcontextprotocol.io) 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](https://docs.astral.sh/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:

```bash
ABUSEIPDB_API_KEY=your_key_here uvx mcp-server-abuseipdb
```

To keep a persistent install on `PATH` instead:

```bash
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:

```json
{
  "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

```bash
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:

```json
{
  "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:

```bash
docker build -t abuseipdb-mcp:local .
```

## Development

```bash
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):

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

Tests and lint:

```bash
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:

```bash
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`](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`.
