stellara-mcp

Stellara MCP：AI エージェントのための決定論的 Swiss Ephemeris（Hermes、Claude、Grok）

AI エージェントに本物の天文計算機能を与えます。 stellara-mcp は、小規模なオープンソースの Model Context Protocol サーバーです。MCP 対応エージェント（Claude.ai／Claude Desktop／Claude Code、ChatGPT、Codex、Cursor、Windsurf、Gemini CLI、Grok、Hermes）を、惑星の位置を決して捏造しない占星術師に変えます。URL で接続すればインストールは不要です。または API キーを使ってパッケージをローカルで実行できます。

Stellara クラウド上で稼働する Swiss Ephemeris（プロの占星術師が使うものと同じエンジン）を基盤とする、次の 4 つのツールを提供します。

ツール	返される内容（正確な JSON）
resolve_birth_place	「Warsaw, 14:30」→ 緯度／経度、IANA タイムゾーン、歴史的に正しい UTC オフセットを反映したタイムゾーン対応の birth_datetime（過去の夏時間ルールや法令による時刻を考慮）、さらに年齢と夏時間の曖昧さを示すフラグを返すため、エージェントが座標やオフセットを推測する必要がありません
calculate_natal_chart	14 個の天体（太陽 → 冥王星、キロン、リリス、ノースノード／サウスノード）について、サイン、度数、絶対経度、ハウス、逆行、速度、赤緯を返します。12 個のハウスカスプ、アセンダント／MC／ディセンダント／IC、正確なオーブと接近中／離反中の別を含むすべての主要アスペクトも返します
get_transits_and_aspects	任意の時点のトランジット位置、オーブと接近中／離反中の別を含む、すべてのトランジットと出生図のアスペクト（惑星とアングル）、各トランジット惑星が位置する出生図のハウスを返します
calculate_synastry	2 人の間のすべてのチャート間アスペクトと正確なオーブ、ハウスオーバーレイ（A の惑星が B のハウスに位置する関係と、その逆）を返します

さらに、2 つの MCP プロンプトもあります。collect_birth_profile は、すべての鑑定に必要なデータ（日付 → 確実性を確認した出生時刻 → 場所 → 任意で都市、名前、性別 → 年齢を含む確認カード）を順を追って収集します。astrologer_system_prompt は、JSON を解釈する際にエージェントを規律あるプロの占星術師のスタイルに切り替えます。

このサーバーは解釈を行わず、LLM も呼び出しません。数値を受け取り、数値を返すプロキシアダプターです。鑑定はエージェントが行い、計算は Swiss Ephemeris が行います。

---

これが必要な理由：LLM は出生図について嘘をつきます

言語モデルに「1990 年 5 月 17 日 14:30、ワルシャワで月はどこにありましたか？」と尋ねると、自信たっぷりに答えます。しかし、その答えはたいてい間違っています。黄道経度、ハウスカスプ、アスペクトのオーブは、惑星運動の数値積分と、地平線に対する球面三角法によって求められます。これは、次のトークンを予測するモデルが頭の中でできることではありません。よくある失敗例は次のとおりです。

• 月（1 日あたり 13° 移動）が間違ったサインに入る；
• 時刻や緯度を無視し、太陽星座からアセンダントを推測する；
• ハウスカスプを捏造する、または暗黙のうちに均等ハウスを仮定する；
• オーブを示さずに「土星と太陽がスクエア」と断言する、または実在しないオーブを付ける；
• 逆行の状態を捏造する。

こうした誤りはどれも、その後に続く解釈全体を損ないます。誤ったアセンダントを基にした鑑定は、どれほど雄弁でも価値がありません。

stellara-mcp は、この問題を根本から解決します。エージェントがツールを呼び出すと、ツールは Swiss Ephemeris 相当の精度を持つ位置情報（1 秒角未満の精度、トロピカル方式、10 種類のハウスシステム、正確なオーブ、実際の惑星速度から算出した接近中／離反中の別）を返します。エージェントはそのデータだけを解釈します。確定的な感覚と、確定的な計算機能を用意し、言語モデルには本当に得意なことを任せます。

---

クイックスタート（ワンクリック設定）

接続方法は2つあります。

• リモート、インストール不要（Claude.ai、Claude Desktop、Claude Code、ChatGPT コネクター、 Grok、MCP URL に対応するすべてのクライアント）：カスタムコネクターを追加し、URL https://mcp.stellara.natlex.it/mcp を設定して、Stellara アカウントでサインインします （Stellara アプリと同じアカウントです。Free は1日10リクエスト、Stellara Pro は5 000リクエストです）。 Claude：Settings → Connectors → Add custom connector → URL を貼り付け → Connect → サインイン。 Claude Code：claude mcp add --transport http stellara https://mcp.stellara.natlex.it/mcp を実行し、 /mcp でサインインします。インストールも設定も不要です。トークンの有効期間は短く、アプリから取り消せます。
• ローカルパッケージ＋API キー（以下）：サーバー、スクリプト、Cursor／Windsurf／Codex、 およびキーの使用を希望する方向けです。stellara.natlex.it/#api で取得できます。 Free（1日5リクエスト）または Stellara API Pro（1日5 000リクエスト、月額 $9）を選ぶと、 1分以内にメールで届きます。その後、クライアントを選択してください。

このパッケージは Node.js ≥ 18.17 で動作し、npx で起動するため、グローバルへのインストールは不要です。 以下の設定はすべて、command、args、env の3行で共通です。

Claude Desktop

claude_desktop_config.json を編集します （macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）：

{
  "mcpServers": {
    "stellara": {
      "command": "npx",
      "args": ["-y", "stellara-mcp"],
      "env": {
        "STELLARA_API_KEY": "sk_stellara_your_key_here"
      }
    }
  }
}

Claude Desktop を再起動します。3つのツールが🔌アイコンの下に表示され、 astrologer_system_prompt プロンプトはプロンプト（+）メニューに表示されます。

Hermes Agent Desktop

同じブロックを ~/.hermes/config.json に追加します：

{
  "mcpServers": {
    "stellara": {
      "command": "npx",
      "args": ["-y", "stellara-mcp"],
      "env": {
        "STELLARA_API_KEY": "sk_stellara_your_key_here"
      }
    }
  }
}

Hermes は次回の起動時にツールを検出します。お使いの Hermes ビルドで MCP サーバーのトップレベルキーが異なる場合も、 command／args／env の3項目はそのままにしてください。これが標準の stdio 起動仕様です。

Cursor / Windsurf

Cursor：Settings → MCP → Add new global MCP server（またはプロジェクト内の .cursor/mcp.json）。 Windsurf：Settings → Cascade → MCP servers（または ~/.codeium/windsurf/mcp_config.json）。どちらも同じ JSON を使用します：

{
  "mcpServers": {
    "stellara": {
      "command": "npx",
      "args": ["-y", "stellara-mcp"],
      "env": {
        "STELLARA_API_KEY": "sk_stellara_your_key_here"
      }
    }
  }
}

その他すべての MCP クライアント（Grok ブリッジ、Continue、Zed、カスタムエージェント）

環境変数 STELLARA_API_KEY を設定して、npx -y stellara-mcp を stdio サーバーとして起動します。 これが連携に必要なすべてです。

ローカルクローンから（開発用）

git clone https://github.com/mihnin/stellara-mcp.git
cd stellara-mcp
npm install && npm run build

その後、上記いずれかの設定で "command": "node", "args": ["/absolute/path/to/stellara-mcp/dist/index.js"] を使用します。

---

会話例

ユーザー： 出生図を作成してください。1990年5月17日14:30にワルシャワで生まれました。それと、今日はなぜ仕事がこんなに重く感じるのか教えてください。

エージェント (astrologer_system_promptを読み込み、14:30が正確か概算かを確認し、resolve_birth_place("Warsaw, Poland", "1990-05-17T14:30")を呼び出して、緯度52.23、経度21.01、Europe/Warsaw、1990-05-17T14:30:00+02:00を取得。その値を使ってcalculate_natal_chartを呼び出し、続いて今日のget_transits_and_aspectsを呼び出します。)

出生図はSwiss Ephemerisの位置データに基づいています。まず、実際の配置を見てみましょう。太陽は牡牛座26°14′、第9ハウス。月は山羊座3°52′、第4ハウス。アセンダントは乙女座8°41′です。出生図で最もタイトなアスペクトは、第5ハウスで土星と海王星がコンジャンクション（オーブ0.6°）していることです。創作活動における、秩序と漂流の間の緊張が生涯続くことを示しています。

今日、重く感じる理由は、トランジットの土星があなたの出生図の太陽とスクエアを形成しており、オーブは1.2°で、まだ接近中だからです。約2週間後の正確なアスペクトに向けて、プレッシャーはさらに高まっています。土星と太陽のスクエアは、義務を詰め込んだリュックを背負うようなものです。成果は出せても、何をするにも余計な労力がかかります。同時に、トランジットの火星は日々の仕事を表すあなたの出生図の第6ハウス（みずがめ座）を通過しており、出生図の水星とコンジャンクションしています。オーブは0.4°で、早口になり、いら立ちやすく、ツールや同僚と口論しやすい配置です。

実践的な見方をすると、今は「始めるより、終わらせる」時期です。締め切りのある2つのタスクを片付け、ブレインストーミングは土星のスクエアが離れてからにし、火星と水星によるいら立ちを、仕事が合っていないサインだと受け取らないでください。可能であれば、出生時刻を分単位で教えてください。乙女座8°のアセンダントはサインの境界に近く、上記のハウス配置は出生時刻によって変わるためです。

この回答にあるすべての度数、オーブ、「接近中」という情報はツールの結果に基づいています。解釈はエージェントによるものです。この区別こそが、すべてです。

---

ツールリファレンス

チャートツールに渡す日時は、タイムゾーン付きのISO-8601形式（1990-05-17T14:30:00+02:00または...Z）にする必要があります。タイムゾーンのない値は、ネットワーク呼び出しの前に拒否されます。座標は10進数の度数（北／東が正）です。想定される手順は、まずresolve_birth_placeを呼び出すことです。このツールは、ユーザーが実際に伝えた情報から、正確にこれらの値を生成します。

resolve_birth_place

入力	型	備考
place	string	自由記述、言語は問いません：Warsaw、Варшава、Springfield, Illinois, USA
local_datetime	string（省略可）	オフセットなしの現地時刻：1990-05-17T14:30、時刻が不明な場合は1990-05-17（12:00を仮定し、その旨を示します）

出力：

{
  "query": "Warsaw", "display_name": "Warszawa, województwo mazowieckie, Polska",
  "latitude": 52.2333742, "longitude": 21.0711489, "timezone": "Europe/Warsaw",
  "local_datetime": "1990-05-17T14:30:00", "utc_offset": "+02:00",
  "birth_datetime": "1990-05-17T14:30:00+02:00", "birth_datetime_utc": "1990-05-17T12:30:00Z",
  "time_assumed_noon": false, "local_time_ambiguity": "none", "age_years": 36,
  "source": "nominatim"
}

birth_datetime、latitude、longitudeは、そのままチャートツールに渡します。 壁時計の時刻が2回発生する場合（秋の時計変更）、local_time_ambiguityはambiguous_dst_fallbackになります。時計が進んでその時刻が存在しない場合は、nonexistent_dst_gapになります。エージェントは、ユーザーがどちらの時刻を意味しているのか確認してください。オフセットはIANAタイムゾーンデータベースに基づいているため、1985年のモスクワは+04:00、2015年のモスクワは+03:00として解決されます。エラーはPLACE_NOT_FOUND（近隣の大きな都市を指定するか、国名を追加してください）とGEOCODER_UNAVAILABLE（一時的なエラーのため、再試行してください）です。ジオコーディングにはOpenStreetMap Nominatimを使用します。リクエストの内容は保存されません。

calculate_natal_chart

入力	型	備考
birth_datetime	string	タイムゾーン付きISO-8601
latitude	number	−90 … 90
longitude	number	−180 … 180
house_system	enum	placidus（既定）、koch、porphyry、regiomontanus、campanus、equal、whole_sign、topocentric、morinus、alcabitius
include_minor_aspects	boolean	既定値はfalse — メジャーアスペクトのみ（コンジャンクション10°、オポジション10°、トライン8°、スクエア8°、セクスタイル6°）

出力（一部抜粋）：

{
  "input": { "birth_datetime_utc": "1879-03-14T10:30:00Z", "latitude": 48.4011, "longitude": 9.9876, "house_system": "placidus" },
  "planets": [
    { "name": "Sun", "sign": "Pisces", "degree": 23.498749, "absolute_longitude": 353.498749,
      "house": 10, "retrograde": false, "speed": 0.995959, "declination": -2.585261 }
  ],
  "houses": [ { "house": 1, "sign": "Cancer", "degree": 7.4423, "absolute_longitude": 97.4423 } ],
  "angles": { "ascendant": {...}, "midheaven": {...}, "descendant": {...}, "imum_coeli": {...} },
  "aspects": [
    { "point_a": "Sun", "point_b": "Mercury", "aspect": "conjunction", "exact_degrees": 0, "orb": 9.627514, "movement": "separating" }
  ],
  "meta": { "engine": "Swiss Ephemeris (kerykeion 5.12.7)", "zodiac": "tropical", "house_system": "placidus", "orbs": {...}, "time_resolution": "minute" }
}

get_transits_and_aspects

入力	型
natal	オブジェクト — calculate_natal_chart と同じフィールド
target_datetime	文字列 — タイムゾーン付きの ISO-8601
include_minor_aspects	ブール値

natal（上記の完全なチャート）、target_datetime_utc、transiting_planets （同じポイント形式に natal_house を追加）、および aspects_to_natal を返します。

{ "transiting": "Saturn", "natal": "Sun", "aspect": "square", "exact_degrees": 90, "orb": 1.21, "movement": "applying" }

movement は、出生時の天体を固定した状態で計算されます。動くのはトランジット天体のみで、その瞬間の実際の惑星速度を用います。

calculate_synastry

入力	型
person_a、person_b	オブジェクト — calculate_natal_chart と同じフィールド
include_minor_aspects	ブール値

両者の完全なチャート、inter_aspects（point_a は A に、point_b は B に属し、orb を含む）、および house_overlays（a_in_b_houses、b_in_a_houses）を返します。

プロンプト：collect_birth_profile

引数（省略可）：language。チャート作成前にエージェントが順番に確認する項目は、1 生年月日 → 2 出生時刻とその確実性（正確／おおよそ／不明 → 12:00 とし、ハウス解釈は行わない）→ 3 出生地。resolve_birth_place で特定し、ユーザーに確認します → 4 現在の都市（省略可。「今日」を現地時間で解釈する場合のみ使用）→ 5 名前（省略可）→ 6 性別（省略可。シナストリーの場合のみ質問）→ 7 特定した座標、タイムゾーン、birth_datetime、年齢を記載した確認カード。Stellara アプリが収集するプロフィールに準じますが、計算に不要な項目は除きます。

プロンプト：astrologer_system_prompt

引数（どちらも省略可）：language — 回答する言語、focus — ユーザーが現在気にかけていること。このプロンプトには同じ聞き取りルールが含まれ、座標とオフセットの取得には resolve_birth_place を必須とします。また、エージェントに対し、ツールの JSON のみを位置情報の情報源として使用すること、オーブを明示すること、接近中／離反中を尊重すること、出生時刻が不明な場合は信頼性の低いハウスを示すこと、解釈と計算を分けることを指示します。

---

設定

変数	必須	デフォルト	用途
STELLARA_API_KEY	はい	—	アクセスキー。X-API-Key として送信されます。stellara.natlex.it/#api から申請してください。設定されていない場合、すべてのツールは入手先を示す明確なエラーを返します。
STELLARA_API_BASE_URL	いいえ	https://api.stellara.natlex.it/api/v1/astrology	セルフホストの Stellara バックエンドを指定します（Cloud Run の生 URL https://stellara-api-923668916124.us-central1.run.app/api/v1/astrology も使用できます）。
STELLARA_TIMEOUT_MS	いいえ	15000	リクエストごとのタイムアウト

エラーは、対応方法を示すメッセージ付きの MCP ツールエラーとして返されます。無効または失効したキー（401）、場所が見つからない場合（404）、レート制限（429、IP あたり 60 リクエスト／分。resolve_birth_place は 20 リクエスト）、1 日のクォータ超過（QUOTA_EXCEEDED を伴う 429 — メッセージには 00:00 UTC にクォータがリセットされる時刻と、キーのアップグレード方法が示されます）、バックエンドの検証詳細（422）、ジオコーダーまたはバックエンドの障害（5xx）、ネットワーク障害、タイムアウトです。設定に問題があっても、起動時にサーバーがクラッシュすることはありません。ツールが呼び出されたときに問題の詳細を説明します。これはデスクトップエージェントが最も適切に処理できる方法です。

キーには次のプランがあります。無料（1 日 5 リクエスト — すべてのツールを試すのに十分です）と Stellara API Pro （1 日 5,000 リクエスト、月額 9 ドル）です。stellara.natlex.it/#api をご覧ください。

リモートモード（Streamable HTTP）

同じパッケージは HTTP サービスとしても実行できます（node dist/remote.js）。https://mcp.stellara.natlex.it/mcp はこのサービスです（Cloud Run、ステートレス、リクエストごとに 1 つの McpServer）。これは OAuth 2.1 のリソースサーバーです。GET /.well-known/oauth-protected-resource/mcp は、クライアントを認可サーバー（Stellara バックエンド、https://api.stellara.natlex.it、DCR + CIMD + PKCE S256）に案内します。認証されていない POST /mcp には WWW-Authenticate: Bearer … resource_metadata="…" を付けて 401 を返します。有効なトークン（OAuth アクセストークン、または Authorization: Bearer として送信される sk_stellara_ キー）は API に転送され、API が日次クォータを適用します。監視には GET /health を使用します。GET /mcp は 405 を返します（SSE ストリームもセッションもありません）。

変数	必須	デフォルト	用途
JWT_SECRET	はい	—	認可サーバーと共有する HS256 シークレット（設定されていない場合、サービスは起動を拒否します）
MCP_PUBLIC_URL	いいえ	https://mcp.stellara.natlex.it	パブリックオリジン。<origin>/mcp がトークンのオーディエンス（RFC 8707 の resource）です
OAUTH_ISSUER	いいえ	https://api.stellara.natlex.it	認可サーバー（RFC 8414 の issuer）
PORT	いいえ	8080	リッスンポート（Cloud Run が設定します）
GLAMA_CLAIM_TOKEN	いいえ	—	設定すると、GET /.well-known/glama.json で Glama コネクターの所有権確認情報を公開します（設計上、公開情報です）
STELLARA_API_BASE_URL、STELLARA_TIMEOUT_MS	いいえ	上記と同じ	stdio モードと同じです

---

計算機のセルフホスト

ツールが利用する計算機は Stellara API（FastAPI + kerykeion / pyswisseph）で、https://api.stellara.natlex.it でホストされています。MCP サーバー自体はステートレスな薄いアダプターです。STELLARA_API_BASE_URL を別の API インスタンスに向けるだけで、その他はすべて同じままです。バックエンドはオープンソースとして公開されていません。プライベートなデプロイについては [email protected] までお問い合わせください。

---

ガイド

• docs/USAGE.ru.md — ユーザー向けガイド（ロシア語）：Claude Desktop / Cursor / Hermes へのインストール、キーの取得、対話の例、エラー発生時の対処方法。
• メンテナー向け運用手順書（npm リリース、公式 MCP Registry、カタログ、リモートサービスのデプロイ）はプライベートな Stellara モノレポ（その中の docs/PUBLISHING.md）にあり、公開されていません。

ソース

このリポジトリは、npm パッケージとリモートサービスの公開ソースです。日々の開発はプライベートな Stellara モノレポで行われ、各リリースは単一のコミット（sync: stellara-mcp <version>）としてここに同期されます。こちらでの Issue は歓迎します。プルリクエストはモノレポにマージされ、次回の同期でこちらに反映されます。

開発

npm install
npm test          # vitest: every behavioural test drives the real MCP protocol
npm run build     # tsc → dist/
npm start         # runs the stdio server

テストでは、インメモリトランスポートを介して MCP Client をサーバーに接続し、fetch をスタブ化したうえで、デスクトップエージェントから見える挙動を正確に検証します。具体的には、ツールの検出、ネットワーク呼び出し前のスキーマ検証、リクエストの形式（URL、ヘッダー、本文）、JSON のパススルー、すべてのエラーマッピング、タイムアウト、プロンプトテキストを確認します。

ライセンス

MIT © Natlex。Swiss Ephemeris は © Astrodienst AG であり、kerykeion を介して、そのライセンスに基づきサーバー側で使用されています。