GeoIP

You can run a dedicated MCP server that provides IP geolocation and ASN lookup using MaxMind GeoIP2 databases. It supports single and bulk IP lookups, country-only queries, distance calculations, caching, health checks, and optional Prometheus metrics for monitoring. This makes it easy to integrate geolocation data into MCP clients and automation workflows.

How to use

You interact with the GeoIP MCP Server using an MCP client through the standard in/out channel. Start the server locally, then issue tooling commands to perform geolocation lookups, ASN information retrieval, country-only queries, and distance calculations. The server returns structured results in formats you choose (JSON, summary, or CSV) and can leverage in-memory caching to speed repeated requests. Use the provided tools to perform common tasks like geolocating a single IP, processing multiple IPs in a batch, or obtaining ASN details for an address.

Typical workflows you can implement include:

• Look up the geolocation for a single IP address and inspect country, city, coordinates, and ASN details.
• Process a list of IP addresses in parallel to speed up bulk analyses.
• Retrieve Autonomous System Number information for routing or ownership context.
• Compute the physical distance between two coordinate points for proximity analyses.
• Check the health of the server and associated databases to ensure up-to-date data.

How to install

Prerequisites

• Python installed on your system
• Access to the internet to download dependencies and GeoIP databases
• A shell or command prompt with permission to install packages and run processes

Step 1. Install dependencies

pip install -r requirements.txt

Step 2. Download GeoIP2 databases
- Create a free MaxMind account and obtain GeoLite2 databases
- Download GeoLite2-City.mmdb and GeoLite2-ASN.mmdb (GeoLite2-Country.mmdb is optional)
- Place the files in a known directory, for example ~/Downloads/

Step 3. Set environment variables
```export GEOIP_CITY_DB="~/Downloads/GeoLite2-City.mmdb"
export GEOIP_ASN_DB="~/Downloads/GeoLite2-ASN.mmdb"
export GEOIP_COUNTRY_DB="~/Downloads/GeoLite2-Country.mmdb" # optional
export GEOIP_CACHE_TTL=3600
export GEOIP_CONCURRENCY=20
export PROMETHEUS_PORT=9000 # optional, for Prometheus metrics```

Step 4. Run the server
```python server.py```

## Additional notes

The server communicates via MCP protocol and uses an in-memory cache to speed repeated lookups. You can enable a Prometheus metrics endpoint if you set PROMETHEUS\_PORT. Health checks and performance monitoring tools are available to keep tabs on system and database health.

## Troubleshooting tips

If you encounter issues, verify that the GeoIP databases are accessible at the paths defined by GEOIP\_CITY\_DB, GEOIP\_ASN\_DB, and GEOIP\_COUNTRY\_DB. Check that the databases are readable and up to date. Ensure GEOIP\_CACHE\_TTL and GEOIP\_CONCURRENCY values are appropriate for your workload. If you enable Prometheus, confirm the port is not blocked by a firewall.

## Available tools

### geolocate\_ip

Retrieve geolocation data for a single IP address, including location and ASN information by default.

### geolocate\_multiple\_ips

Process a batch of IP addresses concurrently to obtain geolocation data.

### get\_asn\_info

Fetch ASN information for a given IP address.

### calculate\_distance

Calculate the distance between two coordinate points, with unit support (km or mi).

### server\_management

Perform server-level actions such as clearing cache, getting stats, or reloading databases.

### geolocate\_country

Perform country-only geolocation for a single IP address.