GeoIP MCP Server

A Model Context Protocol (MCP) server providing IP geolocation and ASN lookup services using MaxMind GeoIP2 databases.

Features

• Single & Bulk IP Geolocation: Lookup for IPv4 and IPv6 addresses, with batch concurrency (configurable via GEOIP_CONCURRENCY).

• ASN Information: Retrieve Autonomous System Number and organization.

• Country-only Lookup: Efficient country-level lookup tool.

• Comprehensive Location Data: Country, city, subdivision, postal code, latitude/longitude, and network info.

• Distance Calculation: Compute distance between two coordinates.

• Caching: In-memory cache for fast repeated lookups (configurable via GEOIP_CACHE_TTL).

• Flexible Output: JSON, summary, and CSV formats.

• Health Checks & Performance Monitoring: Tools for server and database health.

• Prometheus Metrics: Optional exporter via PROMETHEUS_PORT.

• MCP Protocol: Compatible with MCP clients.

Related MCP server: Playable Locations MCP Server

Setup

1. Install Dependencies

2. Download MaxMind GeoIP2 Databases

• Register for a free MaxMind account: https://www.maxmind.com/

• Download GeoLite2-City.mmdb and GeoLite2-ASN.mmdb (and optionally GeoLite2-Country.mmdb).

• Place them in a known directory (e.g., ~/Downloads/).

3. Set Environment Variables

Usage

Run the Server

The server communicates via MCP protocol (stdio by default).

Available Tools

1. geolocate_ip

Get geolocation for a single IP.

Parameters:

• ip_address (string, required)

• include_asn (boolean, default: true)

• output_format (json|summary|csv, default: json)

• use_cache (boolean, default: true)

2. geolocate_multiple_ips

Batch geolocation for multiple IPs (concurrent, configurable).

Parameters:

• ip_addresses (array of strings, required)

• include_asn (boolean, default: true)

• output_format (json|summary|csv, default: json)

• use_cache (boolean, default: true)

3. get_asn_info

Get ASN info for an IP.

Parameters:

• ip_address (string, required)

4. calculate_distance

Calculate distance between two coordinates.

Parameters:

• lat1, lon1 (float, required): Point 1

• lat2, lon2 (float, required): Point 2

• unit (km|mi, default: km)

5. server_management

Server operations.

Parameters:

• action (clear_cache|get_stats|reload_databases, required)

6. geolocate_country

Country-only geolocation for a single IP.

Parameters:

• ip_address (string, required)

• output_format (json|summary|csv, default: json)

• use_cache (boolean, default: true)

Example Output

Error Handling

• Invalid IP address formats

• Missing or unreadable database files

• IP not found in database

• Network/database errors

Health & Monitoring

• Use health_check.py for system/database health.

• Use performance_monitor.py for performance metrics.

• Prometheus metrics available if PROMETHEUS_PORT is set.

Docker

A Dockerfile and docker-compose.yaml are provided.

License

This project is licensed under the GNU GPL v3.

Credits