MCP Server

Give AI assistants access to NetLoc8 IP geolocation via the Model Context Protocol.

Overview

The NetLoc8 MCP server lets AI assistants (Claude Code, Claude Desktop, Cursor, VS Code Copilot, and others) perform IP geolocation lookups, manage API keys, and access account data — all through natural conversation.

The server works with or without an API key. Without a key, you get country-level geo data and local utility tools. With a free key, you unlock city-level detail, coordinates, timezone, and account management.

Installation

Bash

go install github.com/netloc8/netloc8-mcp@latest

Prerequisites

Requires Go 1.26+. The binary installs to $GOPATH/bin (or $HOME/go/bin).

Configuration

Add the server to your AI client's MCP configuration. Replace sk_live_YOUR_KEY with your API key, or remove the env block to run in unauthenticated mode.

Claude Code

One-liner:

Bash

claude mcp add --env NETLOC8_API_KEY=sk_live_YOUR_KEY netloc8 -- netloc8-mcp

Or add to .mcp.json in your project root (committable):

JSON

{
  "mcpServers": {
    "netloc8": {
      "command": "netloc8-mcp",
      "env": {
        "NETLOC8_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

JSON

{
  "mcpServers": {
    "netloc8": {
      "command": "netloc8-mcp",
      "env": {
        "NETLOC8_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

JSON

{
  "mcpServers": {
    "netloc8": {
      "command": "netloc8-mcp",
      "env": {
        "NETLOC8_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json in your project root:

JSON

{
  "servers": {
    "netloc8": {
      "command": "netloc8-mcp",
      "env": {
        "NETLOC8_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

OpenAI Codex

One-liner:

Bash

codex mcp add --env NETLOC8_API_KEY=sk_live_YOUR_KEY netloc8 -- netloc8-mcp

Or add to ~/.codex/config.toml (global) or .codex/config.toml (project):

toml

[mcp_servers.netloc8]
command = "netloc8-mcp"
env = { NETLOC8_API_KEY = "sk_live_YOUR_KEY" }

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

JSON

{
  "mcpServers": {
    "netloc8": {
      "command": "netloc8-mcp",
      "env": {
        "NETLOC8_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Antigravity

Add to ~/.gemini/config/mcp_config.json:

JSON

{
  "mcpServers": {
    "netloc8": {
      "command": "netloc8-mcp",
      "env": {
        "NETLOC8_API_KEY": "sk_live_YOUR_KEY"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
`NETLOC8_API_KEY`	No	Your NetLoc8 API key. Enables city-level data and account management.
`NETLOC8_API_URL`	No	Override the API base URL (default: https://api.netloc8.com).

Available Tools

Geo Lookup

Work with or without an API key. Unauthenticated mode returns country-level data only.

Tool	Description
`geolocate_ip`	Look up geolocation for any IPv4/IPv6 address
`geolocate_me`	Look up geolocation for the server's own IP
`get_timezone`	Get IANA timezone for an IP address
`validate_ip`	Check if a string is a valid IP address

Local Utilities

Run locally with no API call and no quota usage.

Tool	Description
`is_public_ip`	Check if an IP is publicly routable
`normalize_ip`	Clean up IP strings (brackets, ::ffff: prefix, whitespace)
`get_subnet`	Derive /24 CIDR prefix from an IPv4 address

Account Management

Require an API key. Not registered in unauthenticated mode.

Tool	Description
`list_api_keys`	List all API keys on your account
`get_usage`	Get request counts and plan limits
`get_profile`	Get account profile (name, email)
`get_audit_log`	View account activity log
`create_api_key`	Create a new API key
`delete_api_key`	Revoke an API key (irreversible)
`renew_api_key`	Extend an API key's expiration

What You Get

Feature	No API Key	Free Key	Paid Key
Country-level geo	✅	✅	✅
City, coordinates, timezone	—	✅	✅
Local utility tools	✅	✅	✅
Account management	—	✅	✅
Monthly requests	—	5,000	25,000+

Get a free API key