GetBirthChart MCP

@getbirthchart/mcp

GetBirthChart の占星術計算向け公式 MCP サーバー 0.2.0 です。公開されている GetBirthChart API を介して、MCP 対応 AI クライアントから構造化された計算結果にアクセスできます。 占星術エンジンを内蔵したり、再実装したりするものではありません。

要件

• Node.js 20 以降
• GetBirthChart の開発者 API キー

キーは getbirthchart.com/developers で作成できます。キーは非公開にし、実際のキーを含む MCP ホスト設定をコミットしないでください。

クイックスタート

このパッケージは MCP stdio 経由で動作し、npx で起動できます。

{
  "mcpServers": {
    "getbirthchart": {
      "command": "npx",
      "args": ["-y", "@getbirthchart/[email protected]"],
      "env": {
        "GETBIRTHCHART_API_KEY": "gbc_live_your_key_here"
      }
    }
  }
}

これは、MCP stdio サーバーに対応したホスト向けの標準的なコマンドベースの設定です。設定ファイルや UI の正確な場所については、ご利用のクライアントの最新ドキュメントを参照してください。このリポジトリでは公式 MCP TypeScript クライアントを使ってプロトコルをテストしており、ベンダー固有のクライアントはテストしていません。

環境変数

変数	必須	説明
GETBIRTHCHART_API_KEY	はい	サーバー側の開発者 API キーです。
GETBIRTHCHART_API_BASE_URL	いいえ	開発／テスト用の HTTPS API ベース URL の上書き値です。HTTP はローカルホストの場合に限り使用できます。

キーは起動時に読み込まれ、ツール引数として受け付けられることも、標準出力、ログ、リソース、ツールの結果に書き込まれることもありません。

利用可能なツール

すべてのツールは読み取り専用で、構造化された計算事実を返します。入力には厳密なフィールドを使用します。date、任意のtimeとplace、必須のlatitude、longitude、timezone、および以下に記載する任意のunknown_timeと計算設定です。

ツール	入力	出力	正確な時刻が必要か？	不明な時刻の動作
calculate_birth_chart	birthData	マッピングされた出生図	いいえ	不確実性を保持し、アセンダントとハウスを省略します。
get_planet_positions	birthData	惑星の配置	いいえ	出生図の不確実性を保持します。
get_big_three	birthData	太陽、月、任意のライジング	いいえ	アセンダントを推測しません。
get_moon_sign	birthData	月星座と不確実性	いいえ	バックエンドが1つの星座を確定できない場合は、曖昧さを返します。
get_rising_sign	birthData	ライジングサイン	はい	birth_time_requiredを返します。
calculate_aspects	birthData	出生時のアスペクト	いいえ	バックエンドが提供する事実のみを返します。
calculate_synastry	person_a、person_b、関係性フィールド	シナストリーのアスペクトと要約	人ごと	各人の不明な時刻に関する制限を保持します。

現在のパブリックAPIはplaceをジオコーディングしません。場所のラベルを含める場合でも、緯度、経度、 IANAタイムゾーンを指定してください。MCP サーバーは出生時刻を作り出しません。バックエンドは不明な時刻の評価で、 ラベル付きの計算基準時刻として現地時間の午前0時を使用する場合がありますが、その基準時刻を本人の出生時刻として提示することはなく、 ハウス、アセンダント、曖昧な月星座を推測することもありません。

入力例：

{
  "date": "1990-01-15",
  "time": "12:00",
  "place": "New York, NY",
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

不明な時刻：

{
  "date": "1990-01-15",
  "unknown_time": true,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

計算オプション

出生図ツールは、公開されているコアのgbc-astro 1.13.0オプションhouse_system、 node_type、aspect_preset、custom_aspect_rules、additional_points、 fold、zodiac、ayanamsaを受け付けます。レガシー互換の既定値を使用するには、これらを省略してください。 トロピカル、プラシーダス、トゥルーノード、標準アスペクト、カイロン有効、リリス無効です。 サイデリアル計算には名前付きのayanamsaが必要です。推奨される製品設定はラヒリです。 カスタムアスペクトにはcustom_aspect_rulesが必要で、各ルールでは type、exact_angle、orbを使用します。

実装では、コアが製品向けに提供するハウスシステム （placidus、whole_sign、equal）に加え、登録済みのエンジンシステム、ミーンノード、 標準／拡張／カスタムの出生図アスペクト、ミーン／トゥルーリリス、バーテックスとパート・オブ・フォーチュンのリクエスト、 名前付きのサイデリアル・アヤナーンシャを公開しています。MCP の契約には、計算ロジックや解釈は追加されません。 コンポジットとデイビソンはコア／SDKの機能ですが、このリリースではMCPツールではありません。

シナストリーでは、両方のチャートで同じノード方式を使用するための関係性レベルのnode_typeに加え、 任意のrelationship_type、topic、target_instantを指定できます。 サーバーはレスポンスのメタデータと、追加されるスキーマ1.xフィールドを保持します。出生図の HTTPレスポンスではcalculationHashが省略される場合がありますが、これは有効であり、必須ではありません。 サーバーは返されたv2:計算ハッシュを変更も切り詰めもせずに保持します。コア互換性は出生図スキーマ1.9.0、シナストリースキーマ 1.5.0です。

リソース

• getbirthchart://methodology — 計算上の規則と出生時刻が不明な場合の境界条件です。
• getbirthchart://data-sources — 天体暦、タイムゾーン、位置情報入力の出典情報です。
• getbirthchart://engine-info — プロバイダーと公開 API のメタデータです。

権威あるウェブ上の参考資料：方法論とデータソースです。

エラー

ツールの失敗時には、安全で機械可読なcode、メッセージ、retryable、および任意のretry_afterを含む構造化されたerrorデータが返されます。一般的なコードには、validation_error、authentication_required、birth_time_required、location_not_found、ambiguous_location、rate_limit_exceeded、timeout、internal_errorがあります。

トラブルシューティング

• API キーがありません： MCP ホストのサーバー環境でGETBIRTHCHART_API_KEYを設定してください。これはツールの引数ではありません。
• 認証エラーまたはレート制限エラー： 構造化エラーのcodeと、存在する場合はretry_afterを使用してください。ツール呼び出しやクライアントのログにキーを含めないでください。
• 出生時刻不明の検証： unknown_timeがtrueの場合はtimeを省略してください。サーバーが正午で代用したり、ライジングサインを作り出したりすることはありません。
• 位置情報の検証： 数値のWGS84latitude、longitude、およびIANAtimezoneを指定してください。placeはラベルにすぎず、ここではジオコーディングされません。
• ローカル開発： GETBIRTHCHART_API_BASE_URLはHTTPS、またはlocalhost上のHTTPでのみ使用してください。信頼できないホストに本番用キーを送信しないでください。

プライバシーとセキュリティ

出生データは、要求された計算のために、設定された公開 API にのみ渡されます。このパッケージは出生情報を永続化、キャッシュ、記録せず、分析やテレメトリーも行いません。任意のベース URL の上書きにより信頼境界が変わります。信頼できないホストに本番用キーを送信しないでください。

セキュリティ上の問題は、SECURITY.mdに記載された手順に従って非公開で報告してください。バグ報告に API キーを含めないでください。

開発

npm install
npm run lint
npm run typecheck
npm test
npm run build

テストではモッククライアントを使用し、本番 API は呼び出しません。ビルド済みサーバーをローカルで実行するには、GETBIRTHCHART_API_KEYを設定してnode dist/cli.jsを実行してください。通常のプロトコル通信は標準出力に出力され、起動エラーは標準エラー出力に書き込まれます。

リンク

• 開発者ハブ
• GitHub リポジトリ
• Core 1.13.0 GitHub リリース
• PyPI の Core 1.13.0
• Core OpenAPI ソース
• コンセプト DOI · バージョン DOI
• npm パッケージ

MCP レジストリのメタデータ

レジストリのメタデータは、サーバー名io.github.getbirthchart-com/getbirthchart-mcpを含むserver.jsonで準備されています。まず npm パッケージを公開し、その後、公式のmcp-publisherツールで認証してメタデータを公開してください。レジストリへの登録は、意図的にパッケージのビルドや CI ワークフローには含まれていません。