geonames-mcp-server

---

概要

GeoNames の地名データベースには、世界中の 1,300 万以上の地名が収録されており、大陸から近隣地域まで行政階層に沿って関連付けられています。地名の検索、完全なレコードの取得、行政階層の参照、座標の逆ジオコーディング、郵便番号の検索、国の情報の取得ができます。

ツール

ツール	説明
geonames_search_places	名前、国、行政区分コード、地物クラスまたはコード、人口規模、バウンディングボックスで地名を検索します
geonames_get_place	1 つの geonameId の完全なレコードを取得します。行政階層、タイムゾーン、標高、別名、郵便番号、外部識別子を含みます
geonames_get_hierarchy	地球と大陸から対象地物までの親階層を取得します
geonames_get_children	行政、観光、または属領の階層における地物の直接の子を取得します
geonames_reverse_geocode	座標の国と行政区分（または海洋）に加え、最寄りの地名または地物と、オプションでタイムゾーンを取得します
geonames_find_postal_codes	郵便番号、地名、または座標の近くから郵便番号を検索します
geonames_get_countries	国の情報を取得します。ISO および FIPS コード、geonameId、首都、人口、面積、言語、通貨、郵便番号の形式を含みます
geonames_list_reference	地物クラス、地物コード、および郵便番号データがある国を取得します

機能リファレンス

geonames_search_places _tool

• query（最大200文字）をmatchに応じて比較します。name_required（デフォルト）、any_field、exact_name、name_prefixから選択できます。countries（最大10件、ISO alpha-2、alpha-3、または数値コード）、adminCode1～adminCode4、featureClasses、featureCodes（最大20件）、cities（cities1000／cities5000／cities15000）、boundingBoxで絞り込めます。呼び出しにはquery、またはcountries、featureClasses、featureCodes、boundingBoxのいずれかが必要です
• 国を指定すると、その国の下にGeoNamesファイルがある地域も返します（GBではIM、GG、JE、GSも返します）。各地名には独自のcountryCodeが付与されます。ページ上でcountriesに含まれていない国がある場合は、通知にその国名が示されます
• adminCode1～adminCode4を使うと、geonames_get_placeとgeonames_reverse_geocodeがadminLevelsで返すGeoNamesコードにより、行政区画内を検索できます（countries: ["US"], adminCode1: "TX", featureCodes: ["AIRP"]ではテキサス州の空港を一覧表示します）。コードでは大文字と小文字が区別されず、ゼロ埋めも判定対象です（2ではなく02）。ISO 3166-2コードや郵便番号ではありません（バイエルン州はBYではなく02です）。それぞれに国を1つだけ指定する必要があり、レベル2～4にはadminCode1が必要です
• limitは1～1,000（デフォルトは10）です。1回の呼び出しでは100件までに制限され、それ以上の結果が残っている場合は通知されます。offsetは0～5000、orderByはrelevanceまたはpopulationです（省略した場合はGeoNames独自の順序）。totalCount、effectiveQuery、nextOffsetを返します
• featureClasses、featureCodes、cities（クラスPのみ）は相互に絞り込みます。両方のリストを指定した場合、各コードのクラスがリストに含まれ、リスト内の各クラスにコードが必要です。citiesと併用できるのはクラスPとそのコードのみです。それ以外の場合はfeature_filter_mismatchエラーになります
• リクエスト前に、query_or_filter_required、query_required、unknown_country_code、unknown_feature_code、admin_code_unscoped、feature_filter_mismatch、invalid_bounding_boxのいずれかで失敗します

---

geonames_get_place _tool

• geonameIdを1つ指定します。不明なIDの場合は、found: falseとguidanceを返します
• adminLevels 1～5（コード、名前、geonameId）、タイムゾーン（1月1日と7月1日のUTCオフセット）、バウンディングボックス、記録された標高とDEM標高、人口、WikipediaのURL、alternateNames、postalCodes、links、identifiers（IATA、ICAO、FAA、Transport Canada、UN/LOCODE、Wikidata）を返します
• nameLanguages（タグは最大20件。zhはzh-CNにも一致）は、alternateNamesのみを絞り込みます

---

geonames_get_hierarchy _tool

• geonameIdを1つ指定します。chainは、地球とその大陸から国、行政区画を経て地物までをたどり、該当しない階層は省略します
• 各階層にはgeonameId、地物クラスとコード、国コードと第1レベルのコード、座標、人口が含まれます。不明なIDの場合はfound: falseを返します

---

geonames_get_children _tool

• hierarchyは、administrative（デフォルト）、tourism（島、海岸、およびその自治体。ほぼすべてがスペインにあります）、dependency（国の従属領）から選択します。子要素は主に行政区画（クラスA）と居住地（クラスP）です。大陸と海岸はクラスL、島はクラスTです
• 地物に該当するツリーがない場合、GeoNamesはtourismまたはdependencyの要求に対して行政上の子要素を返します。このツールは2つのリストを比較し、一致する場合は通知とともにsameAsAdministrativeを設定します。実際のツリーも一致する場合があるため、行はそのまま残ります
• 親ごとに最大1,000件の子要素を1回取得してキャッシュするため、nameContains、limit（1～1,000、デフォルトは100、1回の呼び出しでは500件までに制限され、それ以上の結果が残っている場合は通知されます）、offsetの指定に追加クレジットはかかりません。GeoNamesにさらに多くの結果がある場合は通知されます
• 不明なIDの場合はfound: falseを返します。末端の場合は、通知とともに空のchildrenリストを返します

---

geonames_reverse_geocode _ツール

• lat / lng から country と adminLevels（ADM5 まで。各レベルには geonameId と、存在する場合は ISO 3166-2 の区分コードが含まれます）を特定します。沖合の場合は ocean を返します
• coastalBufferKm（0～50、既定値は 0）を指定すると、地点がどの国にも含まれない場合に、指定した距離内で最も近い国を照合します。港、桟橋、海岸線での位置情報に利用でき、バッファーによる照合では country.distanceInKm が含まれます。近隣地点とタイムゾーンの検索には正確な地点が使用されます
• nearby には、最寄りの人口集積地が表示されます（nearbyLimit は 0～1,000、既定値は 5。1 回の呼び出しでは 50 件までに制限され、半径内にそれ以上ある場合は通知されます。radiusKm は最大 300、既定値は 20。任意で cities ティアを指定できます）。featureClasses / featureCodes を設定した場合は、その種類の最寄りの地物が表示されます。どちらの検索かは nearbyKind で示されます。featureClasses と featureCodes は両方の条件に一致する地物が対象です
• リクエストを送信する前に、conflicting_filters（cities と地物フィルターの併用）、unknown_feature_code、または feature_filter_mismatch（コードのクラスが指定されていない、または指定されたクラスにコードがない）としてエラーになります
• includeTimezone を指定すると、IANA ID、UTC オフセット、現地時刻、日の出、日の入りが追加されます（オフセットは沖合の場合に限られ、日の出と日の入りはどちらも標準オフセットで報告されます）

---

geonames_find_postal_codes _ツール

• mode は code（postalCode が必要）、place_name（placeName が必要）、nearby（lat と lng が必要。radiusKm は最大 30、既定値は 10）のいずれかです。必須フィールドがない場合、または nearby で countries を指定した場合や offset が 0 より大きい場合は、mode_fields_mismatch としてエラーになります
• code と place_name では、ISO の alpha-2、alpha-3、または数値コードで countries をフィルタリングします（250 の国コードに加えて、廃止された AN、CS、YU も指定できます。それ以外のコード（EL や ZZZ など）は unknown_country_code としてエラーになります）
• 国を指定すると、GeoNames のファイルでその国に属する領域も返されます（GB では IM、JE、GG も返されます）。各郵便番号には、その地域独自の countryCode が付与されます。ページ内に countries で指定されていない国がある場合は、その国を通知します
• limit は 1～1,000（既定値は 10）です。1 回の呼び出しでは 100 件までに制限され、さらに結果がある場合は通知されます。code と place_name は offset 0～5000 でページ分割され、オフセット 5000 より前にさらに行がある場合は nextOffset を返します。GeoNames は合計件数を報告しないため、truncated は残りの行があるかどうかを示しますが、その件数は示しません
• 122 か国に対応しています。アイルランドでは Eircode のルーティングキーのみ、マルタではアルファベットの接頭辞のみを返します

---

geonames_get_countries _ツール

• ISO の alpha-2、alpha-3、または数値コード、continent、nameContains で最大 250 か国を指定できます。フィルターを指定しない場合は、全 250 か国が対象です。limit は 1～1,000（既定値は 50）で、1 回の呼び出しでは 250 件までに制限されます。offset も指定できます
• 各行には、ISO コードと FIPS コード、geonameId（geonames_get_children の起点）、首都、人口、面積、大陸、言語、通貨、郵便番号の形式、本土のバウンディングボックスが含まれます。不明なコードは notFound に含まれます

---

geonames_list_reference _ツール

• topic は feature_classes（9 件）、feature_codes（684 件。featureClass でフィルタリング可能）、postal_countries（122 件。各国のコード範囲と件数を含む）のいずれかです。別のトピックで featureClass を指定すると、filter_not_applicable としてエラーになります
• nameContains、limit 1～1,000（既定値は 100。1 回の呼び出しでは 700 件までに制限され、すべてのトピックの結果を収められます）、および offset を指定できます。地物クラスとコードは同梱され、クレジットを消費しません

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、差し替え可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

GeoNames 固有の機能：

• データは GeoNames のもので、CC BY 4.0 のライセンスで提供されています。結果を引き継ぐ場合は GeoNames のクレジットを表示してください。このサーバーは GeoNames とは独立しています。
• アカウントごとに1時間あたり1,000リクエストのペース制限があり、クォータエラーの後はクールダウンが適用されます。クールダウンの影響を受けるのは該当アカウントだけです。
• 呼び出し元をまたいでレスポンスがキャッシュされます。検索結果は1時間、タイムゾーンはキャッシュなし、それ以外のルックアップは24時間です。キャッシュヒットではクレジットを消費しません。
• 入力は柔軟に解釈されます。alpha-3 および数値の国コード、GB に対する UK、LI に対する FL を受け付けます。また、公開されているスキーマでは対象外の形式（リストのカンマ区切り文字列、列挙値やコードの異なる大文字・小文字表記、P.PPLC のクラス接頭辞、geonames.org の URL、geonameId の JSON 整数、郵便番号の余分なスペース、geonamesUsername の代わりの username）もサーバーは受け付けます。ただし、引数を検証するクライアントはそれ以外の形式を拒否するため、ツールの説明には標準形式のみを記載しています。

エージェントに適した出力：

• 型付きの失敗理由により、呼び出し元のアカウント（caller_account_rejected）と運用者のアカウント（server_account_rejected）、消費済みのクォータ（quota_exhausted。data.window は hour、day、week、local のいずれか）、GeoNames が拒否した値（upstream_rejected_parameter）を区別します。
• 不明な ID はエラーではなく、guidance とともに found: false を返します。空または一部のみのページには、次の offset または条件を緩和するためのフィルターを示す notice が含まれます。
• 「なし」を示す GeoNames のプレースホルダー（population: 0、空の行政区名、geonameId: 0）は事実として報告せず、除外します。

既知の制限事項：

• 共有デプロイではクォータも共有されます。 独自のユーザー名を持たないすべての呼び出し元が、サーバーアカウントの1時間あたり1,000クレジットを共有します。リバースジオコーディングが集中すると（1回あたり最大7クレジット）、クォータを使い切る可能性があります。また、GeoNames はウィンドウがリセットされるタイミングを示しません。
• 無料プランでは、検索と郵便番号検索は offset 5000 までに制限されます。1ページあたり最大100行のため、結果セットのうち5,100行目まで取得できます。近隣の郵便番号検索ではページ分割されません。
• 親ごとの子要素数は最大1,000件です。
• 郵便番号データの対象は122か国です。 アイルランドとマルタではコードの接頭辞のみが返されます。米国の近隣検索では、最初の行が ZIP コードの中心点ではなく検索地点に配置されます。
• 近隣検索の半径上限は、地名と地物が300 km、郵便番号が30 kmです。これは GeoNames の無料プランの上限です。
• バウンディングボックスは180°経線をまたげません。 そのような範囲は2つの検索に分割してください。
• 海岸沿いの地点は、バッファーなしでは海上と判定される場合があります。 デフォルトでは、地点を含む国のみが一致します。そのため、港や海岸線上の地点が国の境界線のすぐ外側にあると、近隣の地名が陸上にあっても海が返されます。最寄りの国に一致させるには coastalBufferKm を設定してください（最大50）。海峡では、どちらの岸にも一致する可能性があります。
• 小国や飛び地は、周囲の国として判定される場合があります。 バチカン市国内の地点はイタリアとして返されます。
• 人口の多い場所として近隣検索に含まれるものには、地区や史跡が含まれます。 人口密度の高い都市では、最寄りの行が PPLX の地区や PPLH の旧地区であることがよくあります。各行の featureCode で種類を確認でき、cities を使うと、人口階層を超える場所に絞り込めます。
• 沖合のタイムゾーンはオフセットのみです。 海上では IANA ID、現地時刻、日の出、日の入りは取得できず、日付指定のオフセットはどちらも標準時のオフセットです（外洋には DST がありません）。
• exact_name は別名や歴史的名称にも一致します。 そのため、結果の name が検索語と異なる場合があります。「Springfield」の検索で、ミズーリ州の Plattsburg や Palmyra が返されることがあります。
• データはコミュニティによって編集され、「現状のまま」提供されます。 人口や標高が記録されていない地物も多数あります。

はじめに

パブリックホストインスタンス

https://geonames.caseyjhand.com/mcp でパブリックインスタンスを利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "geonames-mcp-server": {
      "type": "streamable-http",
      "url": "https://geonames.caseyjhand.com/mcp"
    }
  }
}

geonamesUsername を指定しない呼び出しでは、ホストインスタンスの GeoNames アカウントが使用されます。このアカウントの 1 時間あたり 1,000 クレジットは、同様の呼び出しを行うすべてのユーザーで共有されます。代わりにご自身のアカウントのクレジットを使用するには、ご自身の geonamesUsername を指定してください。

セルフホスト／ローカル

GeoNames のユーザー名をプレースホルダーの代わりに指定して、MCP クライアントの設定ファイルに以下を追加してください。

{
  "mcpServers": {
    "geonames-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/geonames-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GEONAMES_USERNAME": "your_geonames_username"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "geonames-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/geonames-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GEONAMES_USERNAME": "your_geonames_username"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "geonames-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "GEONAMES_USERNAME=your_geonames_username",
        "ghcr.io/cyanheads/geonames-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動してください。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 GEONAMES_USERNAME=your_geonames_username bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24+）。
• 無料の GeoNames アカウントを作成し、アカウントページで無料のウェブサービスを有効にしてください。有効にするまでは、GeoNames はそのアカウントからの呼び出しを拒否します。

インストール

1. リポジトリをクローンします。

git clone https://github.com/cyanheads/geonames-mcp-server.git

2. ディレクトリに移動します。

cd geonames-mcp-server

3. 依存関係をインストールします。

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env and set GEONAMES_USERNAME

設定

GeoNames への呼び出しにはすべて、GeoNames アカウントのクレジットが使用されます。GEONAMES_USERNAME はサーバーのアカウントを指定します。GeoNames の無料アカウントを使用し、アカウントページで無料のウェブサービスを有効にしてください。すべてのツールには geonamesUsername も指定できるため、共有環境の呼び出し元は、サーバーではなく自身のアカウントを使用できます。どちらも設定されていない場合、呼び出しは username_required エラーで失敗します。アカウントなしで使用できるのは、geonames_list_reference の組み込みトピック feature_classes と feature_codes のみです。

無料アカウントでは、1 時間あたり 1,000 クレジット、1 日あたり 10,000 クレジットを利用できます。キャッシュ済みの検索ではクレジットは消費されません。

ツール	呼び出しあたりのクレジット
geonames_search_places、geonames_get_place、geonames_get_hierarchy	1
geonames_get_children	1。親の行政区リストがキャッシュされていない場合、tourism または dependency は 2
geonames_find_postal_codes	1（code、place_name。countries を指定して結果が見つからない場合、郵便番号のカバレッジリストがキャッシュされていなければ 1 を追加）；2（nearby）
geonames_reverse_geocode	包含判定に 1（coastalBufferKm の有無を問わず）。最寄りの人口密集地には 3、最寄りの地物には 4 を追加。いずれの国にも含まれず、バッファー内にも国がない場合は海洋の判定に 1、タイムゾーンの判定に 1
geonames_get_countries	1 日あたり 1。国の一覧はキャッシュされます
geonames_list_reference	feature_classes と feature_codes は 0；postal_countries は 1 日あたり 1

変数	説明	デフォルト
GEONAMES_USERNAME	呼び出しで geonamesUsername が指定されていない場合に使用する GeoNames アカウント。geonames.org で無料のアカウントを作成し、アカウントページで無料のウェブサービスを有効にしてください。	なし
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。.env.example と Docker イメージでは stateless に設定されています。	auto
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しの引数と結果を、キー名に基づいて情報を伏せて記録します。GeoNames のユーザー名は、geonamesUsername、username、または user や account という語を含む類似のキーで伏せられます。	false
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

省略可能なオーバーライドの全一覧は、.env.example を参照してください。

サーバーの実行

ローカル開発

• 本番バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行する：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイント：サーバーの指示、ツールの登録、GeoNames サービスのセットアップと終了処理を行います。
src/config	Zod による GEONAMES_USERNAME の解析と検証を行います。
src/mcp-server/tools	8 つのツール定義（*.tool.ts）と、それらが共有する入力（shared-inputs.ts）を格納します。
src/services/geonames	GeoNames サービス：境界の取得、ステータスのマッピング、再試行、アカウントごとの呼び出し間隔調整、レスポンスキャッシュ、パーサー、同梱のフィーチャーコードおよび国コードのテーブルを扱います。
src/utils	GeoNames が作成したテキストおよび呼び出し元からエコーバックされたテキストを、format() の出力とエンリッチメントの末尾部分にレンダリングする際に使用するインラインテキストサニタイザーです。
tests/	src/ の構造を反映したユニットテストと統合テストを格納します。
docs/design.md	設計に関するメモ：ツールの機能、認証情報のモデル、上流の動作。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch を使わないでください。
• ログには ctx.log を、ストレージには ctx.state を使用します。
• 新しいツールは src/mcp-server/tools/definitions/index.ts に登録します。
• 外部 API 呼び出しは、未加工データを検証 → ドメイン型に正規化 → 出力スキーマを返す、という手順でラップします。不足しているフィールドを捏造しないでください。

コントリビューション

Issue の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 ライセンスのもとでライセンスされています。詳細は LICENSE ファイルを参照してください。