# VPNDetection [Health: Active]

**Category:** 🔒 Security  
**Repository:** https://github.com/vpndetection-io/mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 2588  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/vpndetection

## Description
VPN, proxy, Tor, hosting and CDN detection for any IP address, from the VPNDetection API.

## Tools
Capabilities this server exposes over MCP:

- **lookup_ip** — Classify a single IPv4 or IPv6 address: whether it belongs to a VPN, a residential, datacenter, mobile or public proxy, a Tor node, a privacy relay or web gateway, a hosting provider or a CDN, with the provider name where we have one. Private and reserved addresses are answered locally and cost nothing. Always read `coverage.note` before concluding anything from a field that is not in the result.
- **lookup_ips** — Classify a list of addresses in one call, returning a map keyed by address so duplicates collapse and the order you passed them stops mattering. Pass the whole list rather than splitting it yourself: a long one is batched for you. Prefer this over repeated `lookup_ip` calls when you already have the list, for example when triaging a log file. An address that fails carries its error in place of a result rather than failing the batch. Always read `coverage.note` before concluding anything from a field that is not in the result.
- **my_entitlement** — What this API key is entitled to and how much of it has been used: the plan, the field tier that decides how much of a lookup answer comes back, the requests counted so far, the allowance, and when it resets. Use it to explain why a field is missing from a lookup, or before a large batch. Usage counts against the anniversary of the subscription rather than the calendar month, and can lag a few seconds behind. A null `hard_limit` means we never stop serving - it is NOT a limit of zero.
- **list_databases** — The database catalog as this API key's organization may see it, one entry per database FAMILY, with `standing` saying where their license stands: `licensed` if the family is theirs today, `expired` if the term has ended, `unlicensed` if it is published but has never been bought. Each entry has a `base` id, which is what the license names, and a `versions` array whose `id` is what the other database tools take - pass `versions[].id` (`cdn_ip_v1`), never the `base` (`cdn_ip`). Ask again rather than holding on to this: it is answered per key and is not the same for everyone.
- **database_metadata** — What is inside one database before you fetch it: the columns in each published format with their types, a few sample rows, the row count, the build date and the file sizes. Use this to answer questions about what a database contains without downloading it - the files reach several GB - and to budget a transfer before starting one.
- **database_checksum** — The published digests for one database file, for verifying a copy you already hold or deciding whether a build has changed since you last fetched it. It is licensed like the download itself, so a database this key cannot download is refused here too. Looking up a checksum is not a download and does not appear in `list_downloads`.
- **list_downloads** — This organization's own recent download attempts, newest first, REFUSALS INCLUDED - a denial carries the `outcome` and `http_status` that answer "it stopped working", which nothing else here can. Use it to explain a failing fetch, to confirm a transfer ran, or to check whether a request was theirs. This is a bounded WINDOW of at most 200 rows, so a database missing from the answer means it is not in this window - never that it was never downloaded.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "vpndetection": {
    "command": "npx",
    "args": ["-y","vpndetection-mcp"],
    "env": {
      "VPNDETECTION_API_KEY": "",
      "VPNDETECTION_BASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `VPNDETECTION_API_KEY`, `VPNDETECTION_BASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What the VPNDetection MCP server does

The VPNDetection MCP server exposes seven read-only tools for querying the VPNDetection API. Its primary purpose is to classify IP addresses and show which detection fields are available to the credential being used. Results can cover VPNs, residential, datacenter, mobile, and public proxies, Tor nodes, privacy relays, web gateways, hosting providers, and CDNs, subject to the account's plan.

The server also exposes account and database information. An agent can inspect its plan and usage, see the licensing standing of published databases, review database structure and sample data, verify published file digests, and check recent download attempts. There is no tool for downloading database files.

## How it works

The VPNDetection MCP server can use the hosted endpoint at `https://mcp.vpndetection.io/mcp` or run locally through the `vpndetection-mcp` npm package. Hosted clients can authorize with a VPNDetection account. Clients without MCP authorization support can provide a bearer token instead.

Address classification is available through `lookup_ip` for one address and `lookup_ips` for a list. Long lists are split into batches by the service, and batch results are keyed by address. Every lookup includes a `coverage` block. Fields listed as unavailable were not included by the plan; their absence must not be interpreted as a negative classification.

## Setup and configuration

A local configuration runs with Node.js 22 or newer:

```json
{
  "mcpServers": {
    "vpndetection": {
      "command": "npx",
      "args": ["-y", "vpndetection-mcp"]
    }
  }
}
```

Set `VPNDETECTION_API_KEY` to unlock the provider name, classification databases, and proxy-family fields available to the key. `VPNDETECTION_BASE_URL` can override the default API endpoint. Without a key, the local free tier provides the `ip` and `is_vpn` fields and allows 1,000 requests per day per source address.

The database tools require the `db.download` scope. The repository states that an organization's `Default` key has this scope. The hosted service uses the account's authorization flow, while the local process can authenticate with the environment variable.

## Tools and capabilities

- `lookup_ip`: classify one IP address.
- `lookup_ips`: classify multiple addresses, batching long lists.
- `my_entitlement`: report plan, field tier, request usage, allowance, and reset timing.
- `list_databases`: show published databases and whether the organization is licensed, expired, or unlicensed.
- `database_metadata`: return columns, sample rows, row count, build date, and file sizes.
- `database_checksum`: return published digests for a database file.
- `list_downloads`: show recent organizational download attempts, including refusals.

## Limitations and notes

The VPNDetection MCP server deliberately does not provide a `my_ip` tool. For hosted calls, the observed address may belong to an intermediary such as a client provider rather than the person making the request. Database files can be several gigabytes, so retrieval is handled through client libraries or the API rather than an MCP download operation.

Usage is measured against the subscription anniversary rather than the calendar month or billing period. A null `hard_limit` means service does not stop at a hard request ceiling; it does not mean the limit is zero.

_Full upstream README: https://allmcps.com/mcp/vpndetection/readme_