@kukapay/whereami-mcp: WhereAmI MCP Server

kukapay/whereami-mcp
0

WhereAmI MCP Server is a lightweight Python-based server that uses your IP address to provide detailed geolocation data such as city, country, and timezone, powered by ipapi.co. Ideal for quick location queries or comprehensive reports.

❓unknown

Author

kukapay

View on GitHubVisit Website

README

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: 
    bash
    git clone https://github.com/kukapay/whereami-mcp.git
cd whereami-mcp
  2. Install dependencies: 
    bash
    pip install mcp httpx
  3. (Optional) Install as an MCP service: 
    bash
    mcp install whereami_mcp.py --name "WhereAmI"

Usage

Running the Server

  • Direct execution: 
    bash
    python whereami_mcp.py
  • Development mode: 
    bash
    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: 
    bash
    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 LICENSE for details.