astronomy-mcp-server

---

概要

あらゆる場所と時刻の天体観測情報を取得できます。空の位置、出没時刻と薄明時刻、月の位相、次の食、分点、衝、合を確認できます。または、今見える天体を尋ねるだけでもかまいません。astronomy-engine を使ってローカルで計算し、オプションで JPL Horizons の暦表や人工衛星の通過にも対応します。

ツール

ツール	説明
astronomy_get_sky_position	1 つの天体または固有名を持つ恒星の視位置：赤経／赤緯、高度／方位角、黄道座標、等級、位相、太陽離角、星座
astronomy_get_rise_set	天体の出、没、南中の時刻に加え、太陽の市民薄明、航海薄明、天文薄明の時刻
astronomy_get_moon_phase	照らされた割合、位相名、朔望月齢、次の 4 つの月相
astronomy_find_events	次の食、分点、至、月の四相、衝、合、最大離角、遠地点・近地点
astronomy_list_visible	現在見える天体：地平線上にある肉眼で見える天体（およびオプションの明るい恒星）を、空の状態による条件判定付きで順位付けして表示
astronomy_get_ephemeris	JPL Horizons による小天体または宇宙機の暦表（オプトイン）
astronomy_get_satellite_passes	SGP4 で伝播した CelesTrak 要素セットを使って、見える人工衛星の通過を表示（オプトイン）

リソース

リソース	説明
astronomy://body/{body}	太陽系天体のリファレンスカード：名称、種類、平均半径、肉眼での可視性

ツールのみを利用するクライアントでも、astronomy_get_sky_position から同じ種類、半径、肉眼での可視性に関する情報をインラインで取得できます。

プロンプト

プロンプト	説明
astronomy_stargazing_plan	場所を指定して星空観察の夜の計画を立てます。天文学ツールとジオコーディングおよび天気の手順を連携させます。

設計の参考資料：docs/design.md。

機能リファレンス

astronomy_get_sky_position _ツール

• body（sun、moon、mercury … pluto）または star が必須です。両方が設定されている場合は star が優先されます。star は一般名またはバイエル符号（Sirius、α CMa）で、同梱の32個の星のカタログから検索されます。見つからない場合は、カタログを示す star_not_found エラーになります。
• equatorial、大気差補正済みの horizontal、ecliptic の座標に加え、magnitude、angular_diameter_arcsec、phase_angle_degrees、illuminated_fraction、sun_elongation_degrees、constellation を返します。
• 太陽系天体には body_metadata、リソースカードの type、mean_radius_km、naked_eye も含まれます。恒星にはこれらはありません。

---

astronomy_get_rise_set _ツール

• 1つの body について、start（デフォルトは現在時刻）から次の count 周期を検索します。count のデフォルトは1です。1回の呼び出しで31件を返します。count を最大366にすると、最初の31件と、シリーズの続きを取得するための start および count を示す通知が返されます。
• 各周期には rise_utc、set_utc、transit_utc、transit_altitude_degrees が含まれます。周極天体または昇らない天体の場合、エラーではなく、日の出・日の入り時刻が null になり、note が返されます。
• body: "sun" の場合、twilight には各周期の日の後の夜について、市民薄明、航海薄明、天文薄明の薄暮・夜明けの時刻が含まれます。最初の日が start より後に始まる場合、極夜で日没がない場合も含め、直前の夜が night_in_progress に格納されます。それ以外の場合、最初の周期にはその夜の情報が含まれます。各薄明・夜明けの時刻ペアはその夜の範囲内に収まり、start より前の時刻も含まれます。

---

astronomy_get_moon_phase _ツール

• 地心基準です。time（デフォルトは現在時刻）のみを受け取り、任意で timezone を指定できます。
• illuminated_fraction、phase_name、age_days、next_quarters、phase_longitude_degrees（新月は0、満月は180）を返します。これは astronomy_get_sky_position の phase_angle_degrees とは異なります。

---

astronomy_find_events _ツール

• 1つの event（solar_eclipse、lunar_eclipse、equinox、solstice、moon_quarter、opposition、conjunction、max_elongation、perigee_apogee）と、次に起こる count 件のイベントを検索します。count のデフォルトは1です。1回の呼び出しで20件を返します。count を最大200にすると、最初の20件と、シリーズの続きを取得するための start および count を示す通知が返されます。検索は2100年末で終了します。
• 天体に関連するイベントでは body が必須です（body_required）。イベントの対象にならない天体を指定すると body_not_supported エラーになります。body2 を指定した conjunction では、body とは異なる月または惑星を指定します（そうでない場合は invalid_body_pair）。結果には separation_degrees が含まれます。
• 日食・月食では、任意で観測者（latitude と longitude の両方が必要です。片方のみの場合は incomplete_observer）を指定できます。指定すると local_visible と contact_altitudes_degrees が追加されます。
• 日食・月食は、ピーク時刻が start 以降のものが含まれます。接触時刻が start より前になる場合もあります。

---

astronomy_list_visible _ツール

• 観測者の座標と、評価する時刻 time（デフォルトは現在時刻。期間ではありません）を指定します。min_altitude（デフォルトは0）と include_stars（デフォルトはfalse）で一覧の内容を調整できます。
• sky_condition（daylight、civil_twilight、nautical_twilight、astronomical_twilight、dark）、sun_altitude_degrees、明るく高度の高い順に並べた bodies を返します。各天体には、昼間、市民薄明、または太陽から15°以内のまぶしさによって見えにくくなる、あるいは暗くなる時間帯を示す visibility_note が含まれます。

---

astronomy_get_ephemeris _ツール

• designation はそのまま Horizons に渡されます（番号付き小惑星の場合は "433;"、周期彗星の場合は "DES=1P;CAP"、宇宙機の場合は負の SPK-ID）。start のデフォルトは現在時刻、stop はその24時間後、step は "1h" です（数値と m、h、d、mo、y のいずれかを組み合わせます）。latitude と longitude を両方指定すると、高度と方位角が追加されます
• 1回の呼び出しにつき最大200行です。truncated が true の場合、通知に再開する start が記載されます。target_name は Horizons が解決した天体名です
• ambiguous_designation、observer_is_target、body_not_found、invalid_step、invalid_elevation、time_out_of_range、request_rejected のいずれかのエラーになり、いずれの場合も修正が必要な入力が示されます
• ASTRONOMY_ENABLE_HORIZONS=true の場合にのみ登録されます

---

astronomy_get_satellite_passes _ツール

• norad_id または name のいずれか一方のみを指定します（ISS、Hubble/HST、Tiangong/CSS は直接解決されます。それ以外の名前は CelesTrak と照合され、候補が一覧表示される ambiguous_satellite_name エラーになります）。start は今日から約1か月以内である必要があり、days のデフォルトは7です
• 1回の呼び出しで10日分を検索します。days を最大30に設定した場合は、最初の10日分を返し、検索を続けるための start と days を通知します
• norad_id、satellite_name、および可視条件を満たす（太陽光を受けており、高度10°を超え、太陽高度が−6°未満）通過情報 passes を返します。各通過情報には、出現・最大高度・消失の時刻と方位角、peak_altitude_degrees、duration_seconds、sunlit、visible_start_utc／visible_end_utc が含まれます
• ASTRONOMY_ENABLE_SATELLITES=true の場合にのみ登録されます

---

astronomy://body/{body} _リソース

• {body} は sun、moon、mercury … pluto のいずれかで、名前補完に対応しています。それ以外は unknown_body エラーになります
• body、name、type（star／planet／moon／dwarf）、mean_radius_km、naked_eye を含む application/json 形式のカードです

---

astronomy_stargazing_plan _{プロンプト}

• 引数：location は必須です。date（YYYY-MM-DD）は任意で、デフォルトは今夜です
• astronomy_get_rise_set（太陽、続いて月）、astronomy_get_moon_phase、include_stars を指定した astronomy_list_visible を連鎖させたユーザーメッセージを1つ返します。また、このサーバーでは対応していないジオコーディングと天気情報の手順も含まれます

機能

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

天文学に特化した機能：

• キー不要、オフライン、決定論的なコア：5 つのコアツールはネットワーク、API キー、レート制限を必要とせず、同じ天体、時刻、観測者に対して常に同じ結果を返します
• エンジンの高精度期間（約 1900～2100 年）外の時刻は time_out_of_range としてエラーになります。Horizons ツールでは、代わりに各天体固有のデータ期間が適用されます
• 時刻は ISO 8601 UTC 形式です。タイムゾーンのない値は UTC として読み取られます。IANA の timezone を渡す（または ASTRONOMY_DEFAULT_TIMEZONE を設定する）と、UTC に加えて *_local フィールドも取得できます。サーバーが座標からタイムゾーンを推定することはありません
• ジオコーディング機能はありません。場所の名前を緯度／経度とタイムゾーンに変換してから、座標を渡してください（elevation のデフォルトは 0 m です）
• オプトイン方式の 2 つの拡張機能には、それぞれ独自のタイムアウトと再試行設定があります。上流で障害が発生すると horizons_unavailable または celestrak_unavailable が返され、コアの出力にフォールバックすることはありません

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

• 不確実性を保持：エンジンで計算できない場合、magnitude、angular_diameter_arcsec、phase_angle_degrees、illuminated_fraction は null になり、「利用不可」と表示されます。ゼロとして扱われることはありません
• 決定論的な可視性メモ：visibility_note は、合成スコアではなく、実際の等級、高度、空の状態、太陽離角に基づきます
• 型付きエラーコントラクト：宣言された各エラーには、型付きの reason と復旧のヒントが含まれるため、呼び出し側で修正して再試行できます
• 丸め表示の背後にある正確な値：format() は、丸めた数値と正確な値を角括弧内に併記します（RA 4.4116 h [4.411597993526305]）。そのため、content[] だけを扱うクライアントでも精度が失われません

はじめに

公開ホストインスタンス

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

Claude Code の場合：

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

Cline の場合（cline_mcp_settings.json）：

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

Cursor の場合（mcp.json）：

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

Claude Desktop では、［設定］→［コネクタ］からリモートサーバーを追加します。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加してください。コアツールに設定は不要です。拡張機能を登録するには、ASTRONOMY_ENABLE_HORIZONS および／または ASTRONOMY_ENABLE_SATELLITES を true に設定してください。

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

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

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

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

{
  "mcpServers": {
    "astronomy-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/astronomy-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 キーは不要です。コアはオフラインで動作し、2 つの拡張機能（JPL Horizons、CelesTrak）もキー不要です。

インストール

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

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

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

cd astronomy-mcp-server

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

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# edit .env only to enable the extensions or override a default

設定

すべての変数は任意です。何も設定しなくてもコア機能は動作します。

変数	説明	デフォルト
ASTRONOMY_ENABLE_HORIZONS	astronomy_get_ephemeris（JPL Horizons）を登録します。	false
ASTRONOMY_ENABLE_SATELLITES	astronomy_get_satellite_passes（CelesTrak + SGP4）を登録します。	false
ASTRONOMY_DEFAULT_TIMEZONE	呼び出しで timezone が省略された場合に使用するフォールバックの IANA タイムゾーンです。未設定の場合、出力は UTC のみです。	none
ASTRONOMY_REQUEST_TIMEOUT_MS	Horizons と CelesTrak のリクエストに対する HTTP タイムアウト（ms）です。	15000
ASTRONOMY_TLE_CACHE_TTL_MS	プロセス内の軌道要素セットキャッシュの TTL（ms）です。デフォルトの 2 時間は、CelesTrak の再取得ガイダンスに準拠しています。	7200000
ASTRONOMY_HORIZONS_BASE_URL	JPL Horizons API エンドポイントです。	https://ssd.jpl.nasa.gov/api/horizons.api
ASTRONOMY_CELESTRAK_BASE_URL	CelesTrak GP エンドポイントです。	https://celestrak.org/NORAD/elements/gp.php
MCP_TRANSPORT_TYPE	トランスポート：stdio または http です。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto です。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth です。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）です。	info
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 astronomy-mcp-server .
docker run --rm -p 3010:3010 astronomy-mcp-server

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

プロジェクト構成

ディレクトリ	用途
src/index.ts	createApp() のエントリーポイントです。ツール／リソース／プロンプトを登録し、サービスを初期化します。
src/config	サーバー固有の環境変数を解析し、Zod で検証します。
src/mcp-server/tools	ツール定義（*.tool.ts）です。コアツール 5 個と、オプトイン拡張機能 2 個があります。
src/mcp-server/resources	リソース定義（*.resource.ts）です。天体の参照カードを提供します。
src/mcp-server/prompts	プロンプト定義（*.prompt.ts）です。天体観測プランを提供します。
src/services/ephemeris	オフライン計算コアです。astronomy-engine ラッパー、天体テーブル、明るい恒星のカタログを含みます。
src/services/horizons	JPL Horizons HTTP クライアント（拡張機能）です。
src/services/satellite	CelesTrak からの軌道要素セット取得と SGP4 による軌道伝播（拡張機能）です。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください。
• リクエストスコープのログには ctx.log を、テナントスコープのストレージには ctx.state を使用してください。
• src/index.ts の createApp() 配列に新しいツールとリソースを登録してください。
• エンジン／API の生の値をドメイン型に正規化してください。不確実な値は null のまま保持し、欠落しているフィールドを決して捏造しないでください。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

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