Metadata-Version: 2.4
Name: ipgeolocateio
Version: 1.0.0
Summary: Zero-dependency Python client for ipgeolocationapi.io: IP geolocation, ASN, timezone, currency, security and bulk lookups
Author-email: "ipgeolocationapi.io" <support@ipgeolocationapi.io>
License: MIT
Project-URL: Homepage, https://ipgeolocationapi.io
Project-URL: Documentation, https://ipgeolocationapi.io/docs
Project-URL: Repository, https://github.com/thebigasif/ipgeolocationapi.io
Project-URL: Changelog, https://ipgeolocationapi.io/blog
Keywords: ip,geolocation,ip-address,geoip,asn,timezone,vpn,proxy,api,security
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# @ipgeolocationapi/mcp

MCP server for [ipgeolocationapi.io](https://ipgeolocationapi.io): IP intelligence
as native tools for Claude Desktop, Cursor, and any MCP-compatible AI.

Ask "where is this visitor from, and is the IP a VPN?" and the AI fetches live
data directly. No custom code.

## Install (30 seconds)

Add to `claude_desktop_config.json` (Claude Desktop > Settings > Developer):

```json
{
  "mcpServers": {
    "ipgeolocationapi": {
      "command": "npx",
      "args": ["-y", "@ipgeolocationapi/mcp"],
      "env": {
        "IPGEO_API_KEY": "ipa_optional_paid_key"
      }
    }
  }
}
```

Restart Claude Desktop. Done. The first run creates a small Python runtime
(one time); macOS and Linux ship with a compatible Python by default.

Cursor and other MCP hosts: same shape, point the command at this package.

## The 10 tools

| Tool | What it returns | Tier |
|---|---|---|
| `ip_lookup` | country, region, city, coordinates, timezone, currency, ASN | free, keyless |
| `security_check` | VPN, proxy, Tor, hosting, relay verdicts + threat score | paid |
| `company_lookup` | organization, registration country, PTR hostname | paid |
| `asn_lookup` | prefixes, route counts, network type | free |
| `timezone_info` | local time, offset, DST transitions | free |
| `timezone_convert` | convert timestamps between IANA zones | free |
| `astronomy` | sunrise, sunset, twilight tiers, golden hour, moon phase | free |
| `parse_user_agent` | browser, engine, OS, device class, bot verdict | free |
| `abuse_contact` | registry abuse mailbox and phone per range | free |
| `bulk_lookup` | up to 100 addresses per call, order preserved | paid |

Free tier: 5,000 calls/day, no key, no signup. Paid modules (security, company,
bulk) need a Business or Max key from the [dashboard](https://ipgeolocationapi.io/dashboard).

## Environment variables

- `IPGEO_API_KEY` - optional. Unlocks the paid tools.
- `IPGEO_BASE` - optional. Defaults to `https://ipgeolocationapi.io`.
- `IPGEO_PYTHON` - optional. Explicit Python 3.10+ interpreter path.

## Plain Python (no npm)

```bash
curl -O https://ipgeolocationapi.io/mcp/mcp_server.py
pip install "mcp==1.26.0" httpx
python mcp_server.py
```

## License

MIT. The API terms apply to the data: https://ipgeolocationapi.io/terms
