IP-API MCP Server

현재 공인 IP 또는 특정 IP 주소의 대략적인 위치 정보를 조회하는 Python FastMCP 서버입니다.

ip-api.com의 무료 JSON API를 MCP tool로 감싸서, AI 클라이언트가 사용자의 현재 네트워크 위치나 특정 IP의 지역 기반 컨텍스트를 확인할 수 있게 합니다.

기능

• lookup_ip_location

  • ip_address를 생략하면 MCP 서버가 실행 중인 컴퓨터의 공인 IP 위치를 조회합니다.

  • ip_address를 넘기면 해당 IPv4 또는 IPv6 주소의 위치를 조회합니다.

  • 국가, 도시, ISP, 위도, 경도, 데이터 출처를 반환합니다.

  • 사용자에게 보여주기 좋은 한국어 message도 함께 반환합니다.

• GET /health

  • 서버 상태 확인용 엔드포인트입니다.

• POST /mcp

  • FastMCP HTTP transport 엔드포인트입니다.

Related MCP server: IP Find

무료 사용 조건

ip-api.com은 비상업적 이용에 한해 API 키 없이 무료로 사용할 수 있습니다.

• 무료 조건: 비상업적 이용, 과제 포함

• API 키: 불필요

• 호출 제한: 분당 45회

• 본인 IP 조회: http://ip-api.com/json

• 특정 IP 조회: http://ip-api.com/json/8.8.8.8

이 서버는 프로세스 내부에서 분당 45회 제한을 방어합니다. 상업적 이용 여부와 최신 정책은 ip-api.com의 공식 약관을 확인하세요.

로컬 실행

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
python server.py

기본 MCP 엔드포인트:

http://localhost:8000/mcp

상태 확인:

curl http://localhost:8000/health

포트를 바꾸려면 PORT 환경 변수를 사용합니다.

PORT=9000 python server.py

MCP Tool

lookup_ip_location

IP 주소 위치 정보를 조회합니다.

입력:

본인 공인 IP 조회:

{}

특정 IP 조회:

{
  "ip_address": "8.8.8.8"
}

출력 예시:

{
  "query": "8.8.8.8",
  "country": "United States",
  "city": "Ashburn",
  "isp": "Google LLC",
  "latitude": 39.03,
  "longitude": -77.5,
  "source": "ip-api.com",
  "message": "IP 8.8.8.8 위치는 United States, Ashburn이며 ISP는 Google LLC입니다."
}

MCP 클라이언트 테스트

서버를 실행한 뒤 다른 터미널에서 실행합니다.

python - <<'PY'
import asyncio
from fastmcp import Client

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        result = await client.call_tool(
            "lookup_ip_location",
            {"ip_address": "8.8.8.8"},
        )
        print(result.data)

asyncio.run(main())
PY

현재 공인 IP를 자동 조회하려면 빈 입력을 넘깁니다.

{}

테스트

source .venv/bin/activate
pytest -q

현재 테스트 범위:

• 본인 공인 IP 조회 엔드포인트 생성

• 특정 IP 조회 엔드포인트 생성

• 응답 필드 정규화

• 잘못된 IP 입력 거부

• ip-api.com 실패 응답 처리

• FastMCP tool payload 생성

• 분당 호출 제한 처리

파일 구조

.
├── server.py
├── requirements.txt
├── requirements-dev.txt
└── tests/
    └── test_server.py

참고

• 위치 정보는 IP 기반의 대략적인 정보이며 GPS처럼 정확하지 않습니다.

• 무료 API는 HTTP 엔드포인트를 사용합니다.

• 서버 재시작 시 인메모리 호출 제한 기록은 초기화됩니다.

• 여러 서버 프로세스를 동시에 실행하면 호출 제한이 프로세스별로 적용됩니다.