usgs-water-mcp-server

---

概要

米国および準州にある、USGSの稼働中の河川観測所と地下水井戸、約8,000か所からリアルタイムおよび過去の水データを取得できます。観測地点を検索し、最新の測定値や過去の時系列データを取得して、今日の流量を数十年分の記録と比較できます。

ツール

ツール	説明
water_list_parameters	よく知られたUSGSのパラメーターコードを名称、単位、分野とともに一覧表示します（ネットワーク呼び出しなし）。または、名称や説明でUSGSの約19,600件の全コードカタログを検索します。
water_find_sites	矩形範囲、州、郡、またはHUC流域でUSGSの観測地点を検索します。地点の種類やパラメーターの利用可否で絞り込めます。該当件数が多い場合はDataCanvasに出力されます。
water_get_readings	最大100か所のUSGS観測地点について、最新の瞬時値（約15分間隔のリアルタイム値）を取得します。
water_get_series	指定した期間における観測地点の毎日または瞬時値の時系列を取得します。期間が長い場合はDataCanvasに出力されます。
water_get_site_data_catalog	カーソルページネーションを使用して、観測地点のパラメーター、センサー、統計情報、UTCでの全記録期間を確認します。
water_get_conditions	全記録期間のパーセンタイル統計と比較して順位付けされた、現在の水文状況を取得します。
water_dataframe_describe	water_get_seriesまたはwater_find_sitesによってDataCanvasにステージングされたテーブルと列を一覧表示します。
water_dataframe_query	water_get_seriesおよびwater_find_sitesによってステージングされた時系列テーブルと地点テーブルに対して、読み取り専用のSQL SELECTを実行します。
water_dataframe_drop	DataCanvasとそのほかのテーブルは残したまま、ステージングされたテーブルを1つ削除します。WATER_DATAFRAME_DROP_ENABLEDによる明示的な有効化が必要です。

リソース

リソース	説明
usgs-water://site/{siteId}	地点のメタデータ：名称、座標、種類、HUC、州、郡、流域面積、標高
usgs-water://parameters	よく知られたパラメーターコードをまとめた一覧（クエリなしでwater_list_parametersが返すリスト）

すべてのリソースデータはツールからも取得できます。地理情報を使って観測地点を検索するには、water_find_sitesを使用してください。

機能リファレンス

water_list_parameters _tool

• queryを指定しない場合：00060（流量、ft³/s）、00065（水位、ft）、72019（地下水位までの深さ、ft）などのコードを含む、厳選された組み込みリストを返します。ネットワーク呼び出しは行いません。group（streamflow、groundwater、temperature、meteorological、water-quality、またはデフォルトのall）で絞り込めます。
• queryを指定した場合：名称または説明でUSGSの約19,600件の全コードカタログを検索します（5桁のコードのみを指定すると、そのコードを返します）。最大25件を返し、それぞれのsource（curatedまたはusgs-catalog）を示します。totalとtruncatedには、一致した全件数に関する情報が含まれます。queryはall以外のgroupと併用できません。
• カタログは最初のクエリ時に取得され、24時間キャッシュされます。取得に失敗すると、再試行可能なupstream_errorとして失敗します。

---

water_find_sites _tool

• 1回の呼び出しで指定できる地理的範囲は1つだけです。bbox（"west,south,east,north"）、2文字のstateCd、カンマ区切りの5桁のFIPS countyCdコード（最大20件）、または2桁か8桁のhucを指定し、siteType（ST、GW、LK、SPなど）、parameterCd、hasDataTypeCd（iv / dv / gw）で絞り込みます。範囲が指定されていない場合、または複数指定されている場合は、NWISへの呼び出し前にmissing_major_filter / conflicting_major_filtersとして失敗します。
• limit（1～500、デフォルトは500）とoffsetを使って該当結果をページングします。truncatedとupstreamTotalには、指定範囲外にある結果の情報が示されます。siteOutput: expandedを指定すると、流域面積と寄与面積が追加されます。
• CANVAS_PROVIDER_TYPE=duckdbの場合、該当する観測地点が500件を超えると、その全件もキャンバスにステージングされます（canvas_id / table_name）。その後、water_dataframe_queryで参照できます。

---

water_get_readings _ツール

• 1回の呼び出しで最大100件のsites、任意のparameterCdフィルター、期間を遡るperiod（ISO 8601、既定値はPT2H）を指定できます。サイト、パラメーター、センサー方式（methodId／methodDescription）ごとに1つの系列を返します。1回の呼び出しにつき最大100系列（サイト間でラウンドロビン方式で保持）、各系列の最新10件のレコードに制限されます。totalSeries、totalValues、truncatedで、上限により含まれなかった内容を示します
• 各値には修飾コード（Pは暫定、Aは承認済み）が含まれます。NWISから結果が返されなかったサイトはmissingSitesに記載されます

---

water_get_series _ツール

• 1回の呼び出しで1つのsiteとparameterCdを指定し、startDate～endDateの範囲を取得します。seriesTypeはdaily（1日あたり1値、既定値）またはinstantaneous（約15分間隔）です。最新500件のレコードがインラインで返され、残りはtotalRecordsとtruncatedで示されます
• 名前付きの系列を1つ返します。既定では、日平均値で、レコード数が最も多いセンサー方式の系列です。statCd（00003は平均、00001は最大、00002は最小。日次のみ）とmethodIdで別の系列を選択できます。otherSeriesには、すべての代替系列とそのレコード数が記載されます
• CANVAS_PROVIDER_TYPE=duckdbの場合、500件を超える範囲の完全な系列はキャンバスに出力されます（canvas_id／table_name）。既存のキャンバスにテーブルを追加するには、以前のcanvas_idを渡します

---

water_get_site_data_catalog _ツール

• 1つのsite、任意のparameterCdとseriesType、およびlimit（1～1000、既定値は100）を指定します。同じフィルターと上限を使い、nextCursorがnullになるまで繰り返します。不明なサイトはnot_foundエラーになり、既知のサイトに一致するメタデータがない場合はseries: []が返されます
• 各行には、OGCのtimeSeriesId、パラメーター名／単位、null許容の統計値、センサーの説明、計算の生データ項目、完全なUTCのbeginDate／endDateが保持されます。Dailyはdailyに、Instantaneousを伴うPointsはinstantaneousに対応し、それ以外の計算ではseriesTypeがnullになります
• water_get_seriesでは、範囲の値からYYYY-MM-DDを取り出します。statCdは日次の行にのみ渡し、methodIdはOGC IDではなく系列の応答から選択します。範囲に欠損期間や遅延した観測値が含まれる場合があります。nullの範囲は不明のままです
• サイトの識別情報とメタデータの取得は、再試行を含めて45秒の期限を共有します。不正な継続カーソル、または拒否された継続カーソルはinvalid_cursorエラーになります。その場合はカーソルを使わずに再開してください

---

water_get_conditions _ツール

• 1つのsiteとparameterCdを指定します。現在の瞬時値を、記録期間中の暦日ごとの日平均パーセンタイルと比較し、percentileClassとして順位付けします。分類はrecord-high（≥p95）、above-normal、normal、below-normal、low、record-low（<p05）、またはデータのない観測値に対するunknownです。percentileLabelにはしきい値を平易な言葉で示し、comparisonBasisにはこの順位付けが概算であり、洪水段階や干ばつの判定ではないことを記載します
• パーセンタイルを適用できない場合でも観測値は返され、historicalContext: nullと、no_record、no_matching_day、no_matching_method、または（一時的な統計サービスの障害を示す）unavailableのいずれかのhistoricalContextStatusが設定されます。複数のセンサーがあるサイトでは、methodIdとmethodMatchedに、読み取ったセンサーと、パーセンタイルがそのセンサー自身の系列から得られたかどうかが示されます

---

water_dataframe_describe _ツール

• water_get_seriesまたはwater_find_sitesによってキャンバスに配置されたテーブルを一覧表示します。各列の名前、DuckDBの型、null許容性が示されます。正確な名前を確認するため、water_dataframe_queryまたはwater_dataframe_dropの前に呼び出してください
• row_countはDuckDBによる推定値であり、正確な件数と異なる場合があります

---

water_dataframe_query _ツール

• ステージング済みテーブルに対する読み取り専用の SELECT を1つ実行します。それ以外のステートメント、システムカタログへのアクセス（information_schema、pg_catalog、duckdb_*）、エンジン設定関数、動的 SQL、ファイル参照は拒否されます。query() は単一の SQL 文字列リテラルを受け付け、同じ制限のもとでチェックされます
• クエリごとに最大10,000行に制限されます。truncated: true は一致する行がさらにあることを示します。WHERE／LIMIT で絞り込むか、真の合計数を確認するには SELECT COUNT(*) を実行してください

---

water_dataframe_drop _ツール

• canvas_id で指定したキャンバスから、table_name（大文字・小文字を区別せず照合）で指定されたステージング済みテーブルを1つ削除します。キャンバスとそのほかのテーブルは残り、応答には削除したテーブルの row_count と remaining_tables が含まれます
• キャンバス上にステージングされていない名前を指定すると table_not_found で失敗し、何も変更されません。そのため、繰り返し削除しても安全です
• オプトイン方式です。WATER_DATAFRAME_DROP_ENABLED=true の場合にのみ呼び出せます。それ以外の場合はランディングページに無効なツールとして表示され、tools/list には含まれません。ほかのデータフレームツールと同様に、CANVAS_PROVIDER_TYPE=duckdb が必要です

---

usgs-water://site/{siteId} _リソース

• サイトのメタデータ（名称、座標、種類、HUC 流域コード、州、郡、流域面積、高度）を application/json 形式で返します
• siteId は8～15桁の USGS サイト番号です。water_find_sites で検索してください

---

usgs-water://parameters _リソース

• よく知られたパラメーターコードをまとめた厳選テーブルを application/json 形式で返します。クエリなしで water_list_parameters が返す一覧です
• パラメーターは不要です。USGS カタログの厳選されたサブセットです。残りを検索するには water_list_parameters の query を使用してください

機能

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

USGS Water 固有の機能：

• NWIS IV（瞬時値）、DV（日次値）、サイト、統計の各エンドポイントに加え、USGS Water Data のパラメーターコード、観測地点、時系列メタデータをラップしています。API キーは不要で、すべて一般公開されています。
• 入力形式は、NWIS が実際に受け付ける形式に照らして入口で検証されます。サイト番号、パラメーターコード、ISO 8601 期間、HUC、FIPS 郡、州、bbox にはそれぞれ検証済みのパターンがあり、ツールの JSON Schema で公開されています。
• HTML エラーの検出：不正な入力に対して NWIS は HTML 本文を含む 400 を返します。サービスレイヤーは NWIS 自身のメッセージを抽出し、型付きの失敗としてマッピングします。
• DataCanvas へのあふれ分の格納：water_get_series（長い日付範囲）と water_find_sites（500 サイトの上限を超える一致セット）は、完全な結果を DuckDB ベースのテーブルとして格納し、water_dataframe_query でクエリできます。あふれ分の格納とデータフレームツールには CANVAS_PROVIDER_TYPE=duckdb が必要です。また、water_dataframe_drop には WATER_DATAFRAME_DROP_ENABLED=true も必要です。
• データがない読み取り値は、データなしのまま扱われます。NWIS が -999999 と報告する値（季節的な休止、廃止、渇水、または故障中の観測所）は、値としてではなく、理由を示す修飾子（Ssn、Dis、Dry、Eqp）を付けた空の value として返され、キャンバス上では NULL として格納されます。
• 地下水の深度は、標準の IV サービスをパラメーター 72019 で読み取ります。従来の gwlevels エンドポイントは 2025 年 11 月に廃止されました。

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

• パーセンタイル分類：water_get_conditions は、呼び出し側がそのまま利用できる percentileClass と、しきい値を平易な言葉で示す percentileLabel を返します。
• 致命的な失敗より部分的な成功を優先：water_get_readings は取得できた時系列を返し、残りを missingSites に列挙します。water_get_conditions は、空の統計テーブル（no_record / no_matching_day）と統計呼び出しの失敗（過渡的な unavailable）を区別し、両方を一つのエラーにまとめません。
• 切り捨ての通知：上限のあるすべての応答（water_get_series、water_find_sites、water_get_readings）は、それぞれの件数と truncated フラグに加え、残りを SQL で取得できる場合は canvas_id / table_name を報告します。
• 構造化コンテンツとレンダリングされたテキストは一致します。ツールが適用する上限と件数はすべて、structuredContent と Markdown に同じ内容で表示されます。

はじめに

公開ホストインスタンス

公開インスタンス https://usgs-water.caseyjhand.com/mcp を利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントから接続してください。

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

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。

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

または、npx を使用する場合（Bun は不要）：

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

または、Docker を使用する場合：

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

DataCanvas は、大きな結果セットに対する SQL 分析用にデフォルトで有効になっています。インラインプレビューのみを返すには、CANVAS_PROVIDER_TYPE=none を設定してください。ポータブルな Claude Desktop バンドルでは、プラットフォーム固有の DuckDB バイナリが含まれていないため、DataCanvas は無効になっています。

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

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

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーは不要です。USGS NWIS は無料の公開 API です。

インストール

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

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

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

cd usgs-water-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# Edit .env to set any optional overrides

設定

変数	説明	デフォルト
CANVAS_PROVIDER_TYPE	water_get_series と water_find_sites の大きな結果を DataCanvas に退避します。無効にするには none を設定します。ポータブルなデスクトップバンドルでは none が設定されます。	duckdb
USGS_USER_AGENT	USGS NWIS および OGC の検出エンドポイントに送信するカスタム User-Agent 文字列です。USGS の利用規約では、説明的な User-Agent が求められています。	usgs-water-mcp-server/0.4.0 (contact: https://github.com/cyanheads/usgs-water-mcp-server)
USGS_REQUEST_TIMEOUT_MS	USGS NWIS および OGC の呼び出しにおける、ミリ秒単位の HTTP リクエストタイムアウトです。サイト系列の検出には、共通の 45 秒の期限もあります。	30000
WATER_DATAFRAME_DROP_ENABLED	true に設定すると、water_dataframe_drop を呼び出せるようになります。オフの場合、このツールは無効として一覧表示されます。削除対象を指定するには CANVAS_PROVIDER_TYPE=duckdb が必要です。	false
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。サーバーはコード内で stateless を宣言しており、.env.example および Docker の実行設定と一致しています。この値を設定すると宣言が上書きされ、auto は stateful に解決されます。	stateless
MCP_AUTH_MODE	認証モード：none、jwt、または oauth です。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）です。	info
LOGS_DIR	ログファイル用ディレクトリです（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果を記録します。キー名による秘匿化が行われ、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限が設定されます。自由形式の値に含まれるシークレットは秘匿化されません。	false
OTEL_ENABLED	OpenTelemetry の計装（スパン、メトリクス、完了ログ）を有効にします。	false

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

サーバーの実行

ローカル開発

• ビルドして実行する：

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

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

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t usgs-water-mcp-server .
docker run --rm -p 3010:3010 usgs-water-mcp-server

Dockerfile では、デフォルトで HTTP トランスポート、ステートレスセッションモードが設定され、ログは /var/log/usgs-water-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	用途
src/index.ts	エントリーポイントの createApp() です。ツール／リソースを登録し、サービスを初期化します。
src/config	Zod を使った、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/mcp-server/resources	リソース定義（*.resource.ts）です。
src/services/nwis	NWIS HTTP クライアントです。IV、DV、サイト、統計の各エンドポイントを扱い、HTML エラーを検出します。
src/services/waterdata	USGS Water Data のサイト系列検出、パラメーターコードカタログの読み込み（24 時間キャッシュ）、および厳選されたパラメーターテーブルです。
src/services/canvas	DataCanvas アクセサー、呼び出し元から渡される canvas_id の解決、および DuckDB を使用した退避用の決定的なテーブル名です。
tests/	src/ の構成に対応する単体テストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• リクエスト単位のログには ctx.log、テナント単位のストレージには ctx.state を使用してください。
• 新しいツールとリソースは、src/mcp-server/*/definitions/index.ts のバレル経由で登録してください。
• 外部 API の呼び出しはラップしてください。生データを検証し、ドメイン型に正規化してから、出力スキーマを返します。不足しているフィールドを捏造しないでください。

貢献

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。