whereami-mcp

whereami-mcp

3
location_services

WhereAmI MCP Server is a lightweight and efficient server that provides precise geolocation information based on the user's IP address. It features dynamic resource fetching, detailed location reporting, and robust error handling, leveraging minimal dependencies.

WhereAmI MCP Server

Python License Status

A lightweight mcp server that tells you exactly where you are based on your current IP, powered by ipapi.co.

Features

  • Dynamic Resources: Fetch specific data (e.g., IP, country, city) via location://{type}.
  • Detailed Tool: Generate a comprehensive location report with get_location().
  • Natural Language Prompt: Ask "Where am I?" to get detailed results.
  • Robust Error Handling: Gracefully manages API and network issues.
  • Minimal Dependencies: Requires only mcp and httpx.

Installation

Prerequisites

  • Python 3.10+
  • pip

Setup

  1. Clone the repository: 
    git clone https://github.com/kukapay/whereami-mcp.git
cd whereami-mcp
  2. Install dependencies: 
    pip install mcp httpx
  3. (Optional) Install as an MCP service: 
    mcp install whereami_mcp.py --name "WhereAmI"

Usage

Running the Server

  • Direct execution: 
    python whereami_mcp.py
  • Development mode: 
    mcp dev whereami_mcp.py

Components

Resource: location://{type}

Returns a specific location detail based on {type}.

  • Supported Types: ip, country, country_code, region, city, latitude, longitude, timezone, isp, asn
  • Examples:
    • @location://ip → "8.8.8.8"
    • @location://city → "Mountain View"
    • @location://country → "United States"
Tool: get_location()

Generates a detailed Markdown table of geolocation data.

  • Fields:
    • IP
    • Country
    • Country Code
    • Region
    • City
    • Latitude
    • Longitude
    • Timezone
    • ISP
    • ASN
  • Sample Output: 
    | Field          | Value             |
|----------------|-------------------|
| IP            | 8.8.8.8           |
| Country       | United States     |
| Country Code  | US                |
| Region        | California        |
| City          | Mountain View     |
| Latitude      | 37.4223           |
| Longitude     | -122.0848         |
| Timezone      | America/Los_Angeles |
| ISP           | GOOGLE            |
| ASN           | AS15169           |
Prompt: where_am_i_prompt

Predefined query: "Please tell me where I am based on my current IP address." Triggers get_location().

Examples in Claude Desktop

  1. Install the server: 
    mcp install whereami_mcp.py --name "WhereAmI"
  2. Query data:
    • "My IP is @location://ip"
    • "I’m in @location://city, @location://country"
  3. Get full report:
    • "Where am I?"
    • get_location()

License

MIT License. See for details.