noaa-marine-mcp-server

---

概要

NOAA CO-OPS と NDBC による米国の潮汐、潮流、水位、ブイ観測データを提供します。沿岸の観測所やブイを検索し、潮汐および潮流の予測、観測水位と月平均水位、ブイのリアルタイム状況、潮流プロファイル、水柱の観測値を取得できます。

ツール

ツール	説明
noaa_marine_find_stations	場所、名称、ID、州、または機能で CO-OPS の潮汐・水位・潮流観測所と NDBC ブイを検索します
noaa_marine_get_tide_predictions	CO-OPS 潮汐観測所の満潮・干潮予測、または 6 分間隔の曲線を取得します
noaa_marine_get_water_level	4 種類の間隔で観測水位を取得し、予測値と高潮残差を併せて表示します
noaa_marine_get_monthly_means	CO-OPS 水位観測所の検証済み月平均潮位基準面と極値を取得します
noaa_marine_get_currents	CO-OPS の潮流予測を取得します。最大上げ潮、最大下げ潮、転流イベント、または 6 分間隔の曲線に対応します
noaa_marine_get_conditions	波、風、海面水温、気温、気圧など、NDBC ブイのリアルタイム状況を取得します
noaa_marine_get_current_profile	NDBC の ADCP ブイから、観測された海流の深度プロファイルを取得します
noaa_marine_get_ocean_observations	NDBC 観測所から、水柱の下層における観測値（水温、塩分、酸素など）を取得します

リソース

リソース	説明
noaa-marine://station/{station_id}	CO-OPS または NDBC ステーションのメタデータ：名称、座標、ソース、対応機能、予測クラス、プラットフォーム

NDBC の owner を除き、リソースのすべての情報は noaa_marine_find_stations の行にも含まれています。ツールのみを呼び出すクライアント向けの情報です。

機能リファレンス

noaa_marine_find_stations _ツール

• フィルターを組み合わせて指定できます：latitude ＋ longitude と radius_km（デフォルト 100、最大 1000）、query（両方のソースで名称または ID の部分一致。距離で並べ替えない場合は、完全一致する ID が優先されます）、state（CO-OPS のみ）、source（coops ／ ndbc ／ all）、types（tide、current、water_level、met、current_profile、water_quality、またはプラットフォームクラスの buoy）。limit のデフォルトは 20、最大は 200 です
• 各ステーションには source、capabilities、type が含まれます。NDBC の場合は platform も含まれます。CO-OPS の行には state（25 km 以内で最も近い州情報を持つステーションから借用した場合は state_derived: true）、潮汐の prediction_class（reference、または reference_id を持つ subordinate）、および各ビンの番号、深度（フィート）、クラスを示す潮流の bins[] が追加されます
• total_found と truncated は limit 適用前の件数を示します。一致なしは applied_search を伴う成功として扱われ、カタログの一部を読み取れなかった場合は sources にフラグが設定され、カタログ全体の読み取りに失敗した場合は sources_unavailable になります。latitude と longitude のどちらか一方だけが指定されている場合は incomplete_coordinates になります

---

noaa_marine_get_tide_predictions _ツール

• interval は hilo（デフォルト）または 6min で、最大 365 日間です。10 種類の基準面（MLLW、MHHW、MHW、MTL、MSL、MLW、DTL、NAVD、STND、CRD）、time_zone（lst_ldt、gmt、lst）、units（english はフィート、metric はメートル）を指定できます
• 6min は基準ステーションでのみ使用できます。従属ステーションでは、基準ステーションを示す subordinate_no_6min エラーが発生します。五大湖のステーションでは no_predictions エラーが発生し、noaa_marine_get_water_level が案内されます
• その他のエラー：invalid_date_range、date_range_exceeded、station_not_found、ステーションが対応する基準面を示す datum_unavailable、および数分で解消する再試行可能な CO-OPS HTTP 403 エラー upstream_throttled

---

noaa_marine_get_water_level _ツール

• interval は 6min（デフォルト、31 日間）、hourly または high_low（365 日間）、daily_mean（3,655 日間、五大湖のみ。常に LST。沿岸ステーションでは great_lakes_only）です。13 種類の基準面（MLLW、MHHW、MHW、MTL、MSL、MLW、NAVD、STND、IGLD、LWD、CRD、LWI、HWI）を指定できます
• 観測値には quality（p ／ v、6min のみ）、sigma（6min および hourly）、type（H ／ HH ／ L ／ LL、high_low のみ）が含まれます。読み取り値のない時間枠は除外され、件数は gaps_dropped に記録されます
• 同じ間隔の予測値も組み合わせて返されます（daily_mean にはありません）。空の系列の理由は predictions_status（empty ／ unavailable）で示されます。residual_summary（max_surge、max_drawdown）は、6min および hourly のみで、一致する期間全体を対象とします。エラー：invalid_date_range、date_range_exceeded、station_not_found、datum_unavailable、no_data、verified_data_lag（より粗い間隔の期間が前月の初日以降で終了しており、CO-OPS による検証がまだ完了していない可能性があります）、および upstream_throttled

---

noaa_marine_get_monthly_means _tool

• 1 リクエストあたり最大 73,000 日分に対応します。english のフィートまたは metric のメートルで、11 種類の基準面（MLLW、MHHW、MHW、MTL、MSL、MLW、NAVD、STND、IGLD、LWD、CRD）を指定できます。返される最初と最後の月は、begin_date と end_date が属する月です
• 月ごとに 1 行を返します。各行には highest、lowest、潮汐基準面（mhhw、mhw、msl、mtl、mlw、mllw、dtl）、潮位差（gt、mn、dhq、dlq）、時間単位の月潮間隔（hwi、lwi）、および inferred コードがそのまま含まれます。CO-OPS が空欄にしている値は省略されるため、五大湖の観測所では highest、msl、lowest のみが含まれます
• エラー：invalid_date_range、date_range_exceeded、station_not_found、datum_unavailable、upstream_throttled。データがない期間については、期間の終了日が前月の初日以降の場合は verified_data_lag、それ以外は no_data が返されます

---

noaa_marine_get_currents _tool

• interval は MAX_SLACK（デフォルト：最高潮、最低潮、転流のイベント）または 6min を指定でき、最大 365 日分に対応します。bin は bins[] から深度ビンを選びます（デフォルトは最も浅いビン）。units は english（ノット、フィート）または metric（cm/s、メートル）です
• すべての応答に bin と depth が含まれます。各行には flood／ebb／slack の type、0 以上の speed、およびその流れの観測所の平均方位を示す direction が含まれます
• 観測所にないビンを指定すると、利用可能なビンを示す bin_unavailable が返されます。CO-OPS がイベントとして予測しない観測所では、説明が notice に記載された空のリストが返されます。予測が公開されていない観測所では predictions_unavailable が返されます。そのほかのエラーは invalid_date_range、date_range_exceeded、station_not_found、no_predictions、upstream_throttled です

---

noaa_marine_get_conditions _tool

• NDBC の station_id を 1 つ指定します。SI 単位で風、波、海面水温、気温、露点、気圧を返します。ただし、tide_ft と visibility_nmi は除きます
• 各センサーフィールドは nullable です。各データブロックには、その項目を含む直近 90 分以内の最新行が使用されます。波については独自の waves_observed_at が示され、その他の古いデータブロックは notice に記載されます。エラー：buoy_not_found、no_sensor_data

---

noaa_marine_get_current_profile _tool

• types: ["current_profile"] を指定して検索した NDBC の station_id を 1 つ指定します。bins[] は最も浅いものから並び、depth_m、direction_deg（真方位、流れの向き）、speed_cm_s を含みます。未報告の場合、後者 2 つは null です
• CO-OPS の予測である noaa_marine_get_currents が返すデータではなく、観測された ADCP 測定値を返します。エラーは、ADCP ファイルがない場合の profile_not_found と no_current_data です

---

noaa_marine_get_ocean_observations _tool

• types: ["water_quality"] を指定して検索した NDBC の station_id を 1 つ指定します。このカタログフラグはデータがあることを保証するものではありません。readings[] には深度ごとに 1 行が含まれ、温度、導電率、塩分、溶存酸素（％および ppm）、クロロフィル、濁度、pH、酸化還元電位を返します
• ほとんどの観測所が報告するのは温度と塩分のみで、未報告の値は null です。エラーは、.ocean ファイルがない場合の observations_not_found と no_ocean_data です

---

noaa-marine://station/{station_id} _resource

• noaa_marine_find_stations の station_id を指定します。このツールの観測所レコードを application/json として返します。NDBC の観測所には owner も含まれ、cacheHint は 6 時間です
• station_not_found は両方のカタログを読み込んだ場合にのみ返されます。片方を読み込めなかった場合は source_unavailable が返されます

特長

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

CO-OPS / NDBC 固有の機能：

• CO-OPS のデータ API とメタデータ API、および NDBC の稼働中ステーションカタログと realtime2 フィード（.txt、.adcp、.ocean）に対応しています。ステーションカタログはメモリに 6 時間キャッシュされます。CO-OPS リクエストには NOAA_APPLICATION_ID の値を application= として含めます。
• ステーション ID はデータソース間で混在しません。CO-OPS の潮汐および水位の ID は数値（9447130）、CO-OPS の潮流 ID は英数字（ACT4176）、NDBC の ID は 5 文字のコード（46041）です。
• CO-OPS ツールでは begin_date / end_date に YYYYMMDD または YYYY-MM-DD を指定します。API 呼び出し前にカレンダー上の妥当性と各ツールの期間上限を検証します（invalid_date_range、date_range_exceeded）。水位の高さはデフォルトで MLLW です。ステーションが対応していない datum を指定すると、対応している datum を示す datum_unavailable が返されます。
• CO-OPS は hourly、high_low、daily_mean、月平均を月に 1 回、前月分について検証します。前月の 1 日以降に終了する期間にデータがない場合は verified_data_lag、それより前の期間にデータがない場合は no_data となります。
• CO-OPS はリクエストが集中すると約 2 分間 HTTP 403 を返します。CO-OPS データツールではこれを再試行可能な upstream_throttled として報告し、復旧までの待ち時間を示します。

エージェントが扱いやすい出力：

• 4 つの CO-OPS 時系列ツールでは、バイト数に基づいてページングします。範囲全体が収まる場合は全データを返し、収まらない場合は先頭ページとともに rows_matched、rows_returned、page_offset、next_offset を返します。offset でページをたどり、limit でページサイズを小さくできます。
• 欠損値は null または省略で表し、捏造しません。NDBC の MM マーカーは null になり、空の CO-OPS 値は削除されます。また、quality はデフォルト値を設定せず省略します。
• 判別可能なフィールドとして、ステーションの source（coops | ndbc）、機能の type、NDBC の platform、prediction_class を用意しています。CO-OPS の水位応答には datum と単位も毎回含めるため、呼び出し側は文字列を解析せず、データに基づいて分岐できます。

はじめに

公開ホストインスタンス

https://noaa-marine.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールも API キーも不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http noaa-marine-mcp-server https://noaa-marine.caseyjhand.com/mcp

Cline の場合（cline_mcp_settings.json）：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "type": "streamableHttp",
      "url": "https://noaa-marine.caseyjhand.com/mcp"
    }
  }
}

Cursor の場合（mcp.json）：

{
  "mcpServers": {
    "noaa-marine-mcp-server": {
      "url": "https://noaa-marine.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

セルフホスト / ローカル

次の内容を MCP クライアントの設定ファイルに追加します。

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

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

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

または Docker を使用します。

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

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 キーは不要です。NOAA CO-OPS と NDBC はオープンデータソースです。

インストール

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

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

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

cd noaa-marine-mcp-server

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

bun install

4. 環境を設定します。

cp .env.example .env
# edit .env if needed (all vars optional)

設定

変数	説明	デフォルト
NOAA_APPLICATION_ID	CO-OPS リクエストで application= として送信する識別子です。	noaa-marine-mcp-server
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_HTTP_HOST	HTTP バインドアドレスです。	127.0.0.1
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイル用ディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果を記録します（キー名のみで秘匿化）。記録サイズは LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES で制限されます。	false
OTEL_ENABLED	OpenTelemetry を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP のベース URL。トレースとメトリクスは、その配下の /v1/traces と /v1/metrics にエクスポートされます。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	オプトイン方式の OTLP ログエクスポートエンドポイントです。ベース URL を設定しても有効にはなりません。	—

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

サーバーの実行

ローカル開発

• ビルドして実行：

  bun run rebuild
  
  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 noaa-marine-mcp-server .
docker run --rm -p 3010:3010 noaa-marine-mcp-server

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

プロジェクト構成

パス	目的
src/index.ts	createApp() のエントリーポイントです。ツールとリソースを登録し、サービスを初期化します。
src/config/	Zod による NOAA_APPLICATION_ID 環境変数の解析です。
src/services/coops/	CO-OPS クライアント：観測所カタログのキャッシュ、データ取得、エラー分類、日付範囲の検証、行のページング、州の解決処理です。
src/services/ndbc/	NDBC サービス：稼働中の観測所の XML と realtime2 フィードのパーサーです。
src/services/geo.ts	近接検索と州の解決処理に使うハーサイン距離です。
src/mcp-server/tools/definitions/	8 つのツール定義（*.tool.ts）です。
src/mcp-server/resources/definitions/	観測所メタデータのリソース（noaa-marine-station.resource.ts）です。
tests/	src/ に対応する Vitest テストです。
docs/	設計ドキュメントとディレクトリツリーです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使いません。
• リクエスト単位のログ記録には ctx.log を使用します。
• ツールとリソースは src/index.ts に直接登録します（このサーバーではバレルファイルを使いません）。
• 外部 API 呼び出しをラップします。生データを検証し、ドメイン型に正規化してから出力スキーマに従って返します。不足しているフィールドを捏造してはいけません。
• NDBC の MM 値は文字列のまま通さず、null に正規化する必要があります。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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