Use This MCP server To

Lookup geolocation data for IP addresses in real time Enrich chat or support logs with user location info Integrate IP location context into security monitoring Provide location-based content customization Automate geolocation tagging in data pipelines Enhance fraud detection with IP region data

README

📝 mcp-ip-geo

English | 简体中文

mcp-ip-geo is an MCP (Model Context Protocol) server that provides IP geolocation lookup services (country, region, city, etc.) using the ip-api.com service.

🔌 MCP Integration

You can integrate the mcp-ip-geo service in two ways:

Method 1: Using the go run command (Stdio)

Add the following to your MCP configuration to run the latest version directly from GitHub:

{
  "mcpServers": {
    "mcp-ip-geo": {
      "command": "go",
      "args": [
        "run",
        "github.com/chenmingyong0423/mcp-ip-geo/cmd/mcp-ip-geo@latest"
      ]
    }
  }
}

Method 2: Using Docker (Streamable HTTP)

🐳 Docker Deployment

Step 1: Clone the repository

git clone https://github.com/chenmingyong0423/mcp-ip-geo.git
cd mcp-ip-geo

Step 2: Build the Docker image

docker build -t mcp-ip-geo-server .

Step 3: Run the container

docker run -d --name mcp-ip-geo-server -p 8000:8000 mcp-ip-geo-server

Once running successfully, the service will listen on 0.0.0.0:8000 within the container (listening on all network interfaces), and can be accessed via http://<server-address>:8000/mcp, where <server-address> can be:

Local development environment: Use localhost or 127.0.0.1
LAN environment: Use the server's internal IP address (e.g., 192.168.x.x)
Public network environment: Use the server's public IP address or domain name

Note: The service is configured to listen on the 0.0.0.0 address inside the container, which is standard practice for containerized applications, ensuring the service can be accessed from outside the container.

Step 4: Configure MCP

Add the following to your MCP configuration:

{
  "mcpServers": {
    "mcp-ip-geo": {
      "url": "http://<server-address>:8000/mcp"
    }
  }
}

Replace <server-address> with the actual server IP address or domain name of your deployment environment.

⚠️ License Notice

Note: This project uses the free version of ip-api.com, which is for non-commercial use only. If you intend to use this project for commercial purposes, please comply with their terms of service or purchase the paid version: https://ip-api.com/

mcp-ip-geo FAQ

How do I integrate mcp-ip-geo with my MCP host?

You can integrate mcp-ip-geo by running it via the Go command or deploying it as a Docker container, then configuring your MCP host to connect to it.

What geolocation details does mcp-ip-geo provide?

It provides country, region, city, and other location details for IP addresses using the ip-api.com service.

Is mcp-ip-geo compatible with multiple LLM providers?

Yes, mcp-ip-geo is model-agnostic and works with OpenAI, Claude, Gemini, and other LLM providers through MCP.

Can mcp-ip-geo handle bulk IP lookups?

While primarily designed for real-time single IP queries, it can be adapted for batch processing with custom integration.

What are the deployment options for mcp-ip-geo?

You can deploy it by running the Go command directly or using the provided Docker image for containerized environments.

How does mcp-ip-geo ensure data accuracy?

It relies on the ip-api.com service, which is regularly updated to provide accurate geolocation data.

Can I customize the data returned by mcp-ip-geo?

Customization depends on the ip-api.com API capabilities; you can filter or select fields as supported by the API.