mcp-ephemeris

@cosmosos/mcp-ephemeris

AI に本物の空を。 Swiss Ephemeris エンジンを利用し、あらゆるアシスタント（Claude、Cursor、エージェント）に計算済みの惑星位置を提供するMCP サーバーです。推測値は一切使用せず、JPL Horizons（NASA）のデータとの照合により、1秒角未満の精度で検証されています。

鉄則：LLM は決して計算しません。 このサーバーは天体暦エンジンへのファサードです。モデルが解釈し、空は事実を示します。

(フランス語版：https://llmastro.com/notre-moteur)

クイックスタート（Claude Desktop）

Settings → Developer → Edit Config を開き、次の内容を追加します。

{
  "mcpServers": {
    "llmastro": {
      "command": "npx",
      "args": ["-y", "@cosmosos/mcp-ephemeris"]
    }
  }
}

Claude Desktop を完全に終了し（システムトレイから）、再起動します。その後、 「今日の月の満ち欠けは？」 と尋ねてください。Claude がサーバーを呼び出し、 実際に計算された位置に基づいて回答します。

Cursor／Windsurf／その他：クライアントの MCP 設定に、同じ llmastro エントリー （command: npx、args: ["-y", "@cosmosos/mcp-ephemeris"]）を追加します。

提供されるツール

19 個のツールすべてが、同じサーバー側の計算エンジンを利用します。

位置と空

ツール	入力	出力
get_planet_positions	datetime（ISO UTC）	すべての天体の黄道上の位置（サイン、度数、逆行）
get_moon_phase	datetime（ISO UTC）	月相、照度％、説明
get_current_sky	latitude、longitude	特定の場所の現在の空（現在のトランジット）
get_aspects	datetime（ISO UTC）	天体間のメジャーおよびマイナーアスペクトの一覧

出生図と相性

ツール	入力	出力
get_natal_chart	出生情報 + zodiac（tropical/sidereal）、houseSystem（7 種類のシステム）	全体的なチャート：ハウス、アスペクト、ASC/MC、月相、ヘルメスのロット
get_transits	出生情報 + datetime（任意）	トランジットと出生図のアスペクト、オーブ順
get_synastry	2 人分の出生情報	チャート間のアスペクト + 調和／緊張の概要
get_composite_chart	2 人分の出生情報	中間点法によるコンポジットチャート
get_secondary_progressions	出生情報 + targetDate	プログレス位置（「1 年を 1 日として計算」）
get_solar_return	出生情報 + year（場所は任意）	ソーラーリターンの時刻とチャート
get_lunar_return	出生情報 + after（任意）	次のルナーリターンの時刻とチャート

天体イベント

ツール	入力	出力
get_ingresses	body、start、end	サイン移動の日付（逆行に対応）
get_retrograde_windows	body、start、end	期間内の逆行／順行への切り替わり
get_eclipse_details	datetime、kind	既知の日食・月食の食分、隠蔽率、サロス周期 (swisseph)
get_next_eclipse	from、kind、backward（任意）	次／前の日食・月食：最大食、種類、接触 (swisseph)

アストロカートグラフィー、数秘術、エンジン情報

ツール	入力	出力
get_astrocartography	datetime（ISO UTC）	惑星の MC/IC ライン + パラン（交差地点）
get_life_path	date（YYYY-MM-DD）	ライフパスナンバー（数秘術）
get_engine_diagnostic	—	使用中のエンジン、ネイティブアドオンの読み込み状況、実際の精度
validate_against_horizons	datetime、bodies（任意）	JPL Horizons（NASA）との位置の差（秒角単位）。ネットワーク接続が必要

(swisseph) = ネイティブ Swiss Ephemeris アドオンが必要です。AstraCore フォールバック時は null を返します。

精度

Swiss Ephemeris を使用した場合、位置は世界標準の**JPL Horizons（NASA）**と1秒角未満の差で一致します（2026-07-19 に測定）。

天体	NASA との差
太陽	0.2″
月	1.5″
木星	0.1″
冥王星	0.4″

validate_against_horizons ツールを使って、ご自身で確認できます。

2つのエンジン

計算はASTRO_ENGINE変数によって振り分けられます。

• swisseph（デフォルト）— Swiss Ephemeris、ネイティブアドオン、サブ秒角の 精度を備えています。C++ビルド環境がある場所（Linux、macOS、多くのサーバー）では 自動的にコンパイルされます。
• astracore — 独自開発の純粋なTypeScriptエンジン（VSOP/Meeus）で、ネイティブ バイナリはありません。swissephをコンパイルできなかった場合（Windowsでよく発生します） に自動フォールバックとして使用されます。太陽と月の精度は維持されますが、外惑星には 数分角のずれが生じます。

エンジンを指定するには、ASTRO_ENGINE=swissephまたはASTRO_ENGINE=astracoreを設定します。

プライバシー

サーバーはお使いのマシン上で動作するため、出生データが外部に送信されることはありません。 validate_against_horizonsのみ、NASAの公開APIにリクエストを送信します。

必要条件

• Node.js ≥ 20。
• 最高精度（swisseph）を得るには、マシン上にC++ビルド環境（python3、make、 コンパイラー）が必要です。それ以外の場合は、設定なしでastracoreに自動フォールバックします。

概要

Llmastroの占星術エンジンを採用しています。精度とアーキテクチャについて詳しくは、 https://llmastro.com/notre-moteurをご覧ください。

ライセンス

非商用利用（個人利用、研究、教育、非営利団体）は無料です。 PolyForm Noncommercial 1.0.0ライセンスに基づきます。

**商用利用／業務利用には有料ライセンスが必要です。**取得するには、 https://llmastro.com/contactからKAIROSAST LTDにお問い合わせください。

注：オプションのswisseph依存関係（Swiss Ephemeris、Astrodienst）には独自のライセンス （AGPLまたはSwiss Ephemerisの商用ライセンス）があり、このライセンスの対象外です。 業務利用では、別途そのライセンスにも準拠する必要があります。

開発

このリポジトリは自己完結型です。天文暦エンジンはvendor/ephemeris/にソースとして 同梱されており、ビルド時にtsupを使ってdist/に インライン化されます。

pnpm install          # or npm install
pnpm build            # bundles dist/index.js (engine inlined)
pnpm start            # runs the MCP server (stdio) locally

• デフォルトのエンジンはswisseph（サブ秒角の精度）です。ネイティブアドオンを コンパイルできない場合は、astracore（純粋なTypeScript、バイナリなし）に自動で フォールバックします。ASTRO_ENGINE=swisseph|astracoreで指定できます。
• 同梱エンジンは@astro-platform/ephemeris（Llmastro）のスナップショットで、手動で再同期します。