IPinfo

IPinfo MCP サーバー

公式の IPinfo MCP サーバーを使うと、Claude などの AI アシスタントが IP アドレスに関する質問に回答できます。IP アドレスの所在地や、どの企業またはネットワークに属しているか、VPN、プロキシ、Tor の出口ノード、またはレジデンシャルプロキシかどうかを尋ねると、アシスタントが IPinfo のデータを使って調べます。

Model Context Protocol（MCP）を実装しています。これは、AI アシスタントが外部ツールに接続するために使うオープン標準であり、MCP 対応のあらゆるクライアントで動作します。IPinfo Lite、Core、Plus、Residential Proxy の各プランに対応しています。

詳細なガイドについては、公式ドキュメントをご覧ください。

インストール

IPinfo アカウントが必要です。ipinfo.io/signup から無料で登録してください。

ホステッドサーバー

MCP クライアントの接続先を https://mcp.ipinfo.io/（Streamable HTTP）に設定します。初回接続時に、OAuth を通じて IPinfo アカウントへのサインインを求められます。

ローカルサーバー（PyPI）

サーバーは PyPI に ipinfo-mcp-server として公開されており、stdio で動作します。API トークンで認証します。uv をインストールしたら、MCP クライアントの設定に追加します。

{
  "mcpServers": {
    "ipinfo": {
      "command": "uvx",
      "args": ["ipinfo-mcp-server"],
      "env": {
        "IPINFO_TOKEN": "<your-ipinfo-token>"
      }
    }
  }
}

Claude Desktop 拡張機能

最新の GitHub リリースから mcp.mcpb をダウンロードし、Claude Desktop で開きます。インストール中に API トークンの入力を求められます。

MCP Registry

サーバーは MCP Registry に io.github.ipinfo/mcp として登録されています（MCP Registry）。

サーバーは LightNow にも登録されています。

ツール

ツール	説明	プラン要件
ipinfo_lookup	IP の詳細データ：位置情報、ネットワーク、メタデータ	すべてのプラン。detailed: true には Core／Plus が必要です
ipinfo_geolocate	地理的位置	すべてのプラン。detailed: true には Core／Plus が必要です
ipinfo_asn	自律システム（ネットワークの所有者）	すべてのプラン。detailed: true には Core／Plus が必要です
ipinfo_check_privacy	VPN、プロキシ、リレー、Tor、ホスティング、エニーキャスト、モバイル、衛星のフラグ	有料プラン
ipinfo_check_residential_proxy	レジデンシャルプロキシの検出	Residential Proxy へのアクセス権
ipinfo_quota	API の使用状況と残りのクォータ	すべて

トークンのプランでアクセスできないツールは、ACCESS_DENIED エラーを返します。

共通パラメーター

ipinfo_quota を除くすべてのツールは、IP アドレスのリストを受け取り、ページネーションに対応しています。

Parameter	Type	Default	Description
ips	string[]	required	パブリック IPv4 または IPv6 アドレスです。プライベート、ループバック、予約済み、マルチキャスト、および bogon アドレスは拒否され、validation_errors に報告されます。
page	integer	1	結果セットの 1 始まりのページ番号です。1 未満の値は 1 に調整されます。
page_size	integer	25	1 ページあたりに解決する IP アドレス数で、最大 1000 です。要求したページの IP アドレスのみ取得されるため、ページサイズが小さいほど、呼び出しあたりのクォータ消費量が少なくなります。

ipinfo_lookup、ipinfo_geolocate、および ipinfo_asn は、次のパラメーターも受け取ります。

Parameter	Type	Default	Description
detailed	boolean	false	false の場合は Lite エンドポイントに問い合わせます。true の場合は、より多くのフィールドを返すフルルックアップエンドポイントに問い合わせます。

共通出力

IP ベースのツールは、次の情報を返します。

Field	Description
results	ツール固有のデータを含む、IP アドレスをキーとしたオブジェクトです。
errors	API がエラーを返した IP アドレスをキーとするオブジェクトです。これらの IP アドレスは results から除外されます。
validation_errors	有効なパブリック IP アドレスではない値をキーとするオブジェクトです。該当する値がある場合のみ含まれます。
_pagination	total_results、page、page_size、total_pages、has_next、has_previous です。
_meta	api_calls_made と from_cache です。結果はメモリにキャッシュされるため、同じ情報を再度検索しても API クォータを消費しません。

リクエスト全体が失敗した場合（トークンがない、または無効な場合など）、ツールは代わりにエラーオブジェクトを返します。このオブジェクトには、code（ACCESS_DENIED、RATE_LIMITED、INVALID_TOKEN、NO_TOKEN、API_ERROR、または UNKNOWN）、message、および suggestion が含まれます。

ipinfo_lookup

各 IP アドレスについて、IPinfo API の生のレスポンスを返します。

• detailed: false（Lite）：ip、asn、as_name、as_domain、country、country_code、continent、continent_code。
• detailed: true（フルルックアップ）：ip、hostname、geo（都市、地域、国、大陸、座標、タイムゾーン、郵便番号）、as（ASN、名前、ドメイン、タイプ）、anonymous（プロキシ、リレー、Tor、VPN）、mobile、および is_anonymous、is_anycast、is_hosting、is_mobile、is_satellite のフラグです。一部のフィールドは Plus でのみ利用できます。

ipinfo_geolocate

各 IP アドレスについて、ip、country、country_code、continent、continent_code を返します。detailed: true の場合は、さらに city、region、region_code、latitude、longitude、timezone、postal_code も返します。

ipinfo_asn

各 IP アドレスについて、ip、asn、name、domain を返します。detailed: true の場合は、さらに type（isp、hosting、business、education）と last_changed も返します。

ipinfo_check_privacy

各 IP アドレスについて、ip、is_anonymous、anonymous（is_proxy、is_relay、is_tor、is_vpn）、is_anycast、is_hosting、is_mobile、is_satellite を返します。

ipinfo_check_residential_proxy

IP ごとに、ip と is_residential_proxy を返します。レジデンシャルプロキシの場合は、さらに service（プロキシサービス名）、last_seen（日付）、percent_days_seen も返します。

ipinfo_quota

パラメーターはありません。token（OAuth で接続している場合は省略）、requests（day、month、limit、remaining）、および features 内の機能ごとのクォータを返します。

設定

サーバーは環境変数で設定します。

変数	デフォルト	説明
IPINFO_TOKEN		API トークン（stdio トランスポート。HTTP ではトークンはリクエストから取得します）
IPINFO_API_BASE_URL	https://api.ipinfo.io	api.ipinfo.io エンドポイントのベース URL
IPINFO_LEGACY_BASE_URL	https://ipinfo.io	従来の ipinfo.io エンドポイント（例：/me）のベース URL
IPINFO_CACHE_TTL	3600	キャッシュされた IP の結果が有効な状態を保つ秒数
IPINFO_TRANSPORT	stdio	トランスポートの種類（stdio または http）
HOST	0.0.0.0	HTTP ホスト（http トランスポートの場合のみ）
PORT	8000	HTTP ポート（http トランスポートの場合のみ）
IPINFO_OAUTH_ISSUER		アクセストークンを受け入れる OAuth 発行者。未設定の場合、OAuth は無効です
IPINFO_MCP_RESOURCE_URL		このサーバーの公開 URL。IPINFO_OAUTH_ISSUER と併用する場合に必要です
IPINFO_OAUTH_JWKS_URI	<issuer>/.well-known/jwks.json	発行者が署名鍵を公開している場所

http トランスポートでは、各リクエストはそれぞれの Authorization: Bearer <token> ヘッダーで認証されます。

IPINFO_OAUTH_ISSUER を設定すると、http トランスポートで OAuth が有効になります。サーバーは /.well-known/oauth-protected-resource で発行者を通知し、有効な認証情報がないリクエストには 401 Unauthorized で応答して、発行者の署名鍵を使ってアクセストークンを検証します。検証済みのアクセストークンは、API トークンの代わりに IPinfo API へ送信されます。API トークンも引き続き従来どおり使用できます。

フィードバック

• バグや機能リクエスト： GitHub Issues で issue を作成してください。
• セキュリティの脆弱性： 公開 issue は作成せず、セキュリティポリシーに従ってください。
• IPinfo アカウントやプランに関する質問： [email protected] までお問い合わせください。

コントリビューション

コントリビューションを歓迎します。ワークフローと変更に求められる要件については、CONTRIBUTING.md をご覧ください。

開発

前提条件

• Python 3.14+
• uv

セットアップ

uv sync --dev
cp .env.example .env
# Add your IPinfo token to .env

サーバーの実行

サーバーは、stdio（デフォルト）と HTTP の 2 種類のトランスポートに対応しています。

# stdio (default, used by MCP clients)
uv run ipinfo-mcp-server

# HTTP
IPINFO_TRANSPORT=http HOST=0.0.0.0 PORT=8000 uv run ipinfo-mcp-server

テスト

# All tests
uv run pytest

# Integration tests (requires IPINFO_TOKEN)
uv run pytest tests/integration/

統合テストでは実際の IPinfo API にアクセスし、レスポンスの構造のみを検証します（値の完全一致は検証しません）。IPINFO_TOKEN の設定が必要です。未設定の場合、テストはスキップされます。

型チェック

uv run pyright

リント

uv run ruff check .
uv run ruff format .