# MCP — Verbindung mit Claude / Cursor Der Model Context Protocol-Server von AstroWay exponiert **alle {siteMeta.endpoints} Endpunkte** als Tools für einen KI-Agenten. Zwei Modi werden unterstützt – beide sind nativ mit allen MCP-kompatiblen Clients kompatibel. | Modus | URL / Befehl | Wann wählen | |---|---|---| | **Hosted HTTP** | `https://mcp.astroway.info/mcp` | Claude Web (claude.ai im Browser), Claude Desktop / Cursor / Code für Einsteiger ohne npm oder wenn du eine Installation vermeiden möchtest | | **Stdio (npm)** | `npx @astroway/mcp` | Cursor Power-User, lokale Entwicklung, Datenschutzbewusste (der Schlüssel verlässt niemals deinen Rechner), offline-fähig | Der Hosted-Endpoint und das npm-Paket nutzen **denselben Tool-Katalog** (wird aus einer einzigen `/v1/openapi.json` generiert). Authentifizierung: Der gleiche `aw_test_*` / `aw_live_*` API-Key – beim Hosted wird er über den `Authorization: Bearer …`-Header gesendet, beim Stdio über die Umgebungsvariable `ASTROWAY_API_KEY`. Quellen: [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp) · npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) · hosted: [mcp.astroway.info/health](https://mcp.astroway.info/health) ## Hosted (`mcp.astroway.info`) – ohne Installation Schneller Einstieg ohne npm – wähle deinen Client. Bevor du installierst, hole dir deinen Schlüssel unter [api.astroway.info/dashboard/sign-up](https://api.astroway.info/dashboard/sign-up) (10.000 Credits/Monat kostenlos). Klicke auf den Button – Cursor öffnet sich, fragt nach Bestätigung und fügt den Eintrag automatisch hinzu: In Cursor installieren → :::caution[Zweiter Schritt ist Pflicht – sonst funktioniert es nicht] Cursor kann den geheimen Schlüssel nicht aus dem Deeplink einsetzen – in `~/.cursor/mcp.json` wird der Platzhalter `Bearer YOUR_API_KEY` eingetragen, woraufhin der Server mit `403 invalid_format` antwortet. **Nach dem Klick auf den Button:** 1. **Cursor-Einstellungen** (⚙️ oben rechts) → **Tools & MCP** → Suche in der Liste nach `astroway-hosted`. 2. Klicke auf die drei Punkte (`⋯`) neben dem Server → **Konfiguration bearbeiten**. 3. Ersetze im Feld `Authorization` den Platzhalter `Bearer YOUR_API_KEY` durch `Bearer aw_test_…` (oder `aw_live_…`) – deinen echten Schlüssel aus dem [Dashboard](https://api.astroway.info/dashboard/keys). 4. Speichere die Änderungen → Öffne die MCP-Liste erneut und stelle sicher, dass der Status **aktiviert** ist, ein grünes Häkchen erscheint und der Zähler `630 tools aktiviert` anzeigt. Alternativ kannst du die Datei direkt bearbeiten: `~/.cursor/mcp.json` (`headers.Authorization`). ::: Ohne Bearbeitung der JSON-Datei. In jedem Chat von Claude Desktop: 1. Klicke auf das **`+`**-Symbol links neben dem Eingabefeld → Wähle im Menü **„Connector hinzufügen“**. 2. Wähle im Dialog **„Benutzerdefinierten Connector hinzufügen“**. 3. **Name:** `astroway-hosted` 4. **URL:** `https://mcp.astroway.info/mcp` 5. Erweitere **„Erweiterte Einstellungen“** → Füge unter **„Benutzerdefinierte Header“** hinzu: - **Schlüssel:** `Authorization` - **Wert:** `Bearer aw_live_…` (dein Schlüssel) 6. **Hinzufügen** → Suche in der Liste der Connectoren nach `astroway-hosted`, aktiviere den Schalter. Ein Neustart von Claude Desktop ist **nicht erforderlich**. Klicke im neuen Chat auf `+` – im Bereich der Connectoren erscheint `astroway-hosted` mit allen 630 Tools + 12 Prompts + 14 Ressourcen. Für Cline / Continue / Windsurf oder ältere Versionen von Claude Desktop / Cursor: ```json { "mcpServers": { "astroway-hosted": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } } } } ``` Pfade zu den Konfigurationsdateien: - **Claude Desktop (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Claude Desktop (Windows):** `%APPDATA%\Claude\claude_desktop_config.json` - **Cursor:** `~/.cursor/mcp.json` (global) oder `.cursor/mcp.json` (im Workspace) - **Cline (VS Code):** `.cline/mcp.json` im Workspace - **Continue:** `~/.continue/config.json` (Block `mcpServers`) - **Windsurf:** `~/.codeium/windsurf/mcp_config.json` Nach der Bearbeitung starte den Client vollständig neu (Cmd+Q → neu öffnen). ### Überprüfung ```bash curl https://mcp.astroway.info/health # {"status":"ok","version":"…","uptime_sec":…,"mcp_protocol_version":"2024-11-05"} ``` Im Client – bitte den KI-Agenten: *„Nenne 5 Tool-Namen von astroway-hosted“*. Es sollten Namen wie `astroway_western_chart`, `astroway_horoscope_daily`, `astroway_vedic_panchang_full`, … zurückgegeben werden. ### Rate-Limits Der Hosted-Endpoint ist durch ein 3-stufiges Limit geschützt: Cloudflare DDoS-Schutz + nginx `120 req/min/IP` + In-Memory-Bucket `60/60s/(IP+Key)`. Echte MCP-Clients (Claude Desktop, Cursor) erreichen diese Limits nicht – sie senden keine Burst-Anfragen. Wenn deine Automatisierung / CI mehr als 120 req/min benötigt, verwende den **Stdio**-Modus (hier gibt es keine Limits, die Anfragen gehen direkt über `api.astroway.info/v1/*` mit deinem tariflichen Rate-Limit). ### Was tun, wenn `mcp.astroway.info` vorübergehend nicht verfügbar ist? Wenn der Hosted-Endpoint einen 5xx-Fehler zurückgibt, sieht der MCP-Client beim Aufruf von `tools/list` einen Fehler. Dies **beeinträchtigt nicht** Stdio-Clients – diese starten das lokale npm-Paket, das direkt mit `api.astroway.info/v1/*` kommuniziert, ohne die Hosted-Schicht. **Fallback für kritische Integrationen:** Füge einen **zweiten MCP-Server** in die Konfiguration im Stdio-Modus hinzu – der Client wechselt automatisch zu diesem, wenn der Hosted-Endpoint nicht auf `tools/list` antwortet: ```json { "mcpServers": { "astroway": { "url": "https://mcp.astroway.info/mcp", "headers": { "Authorization": "Bearer aw_live_..." } }, "astroway-fallback": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Die tatsächliche Verfügbarkeit des Hosted-Endpoints siehst du unter [status.astroway.info](https://status.astroway.info). Bei Ausfällen von mehr als 5 Minuten veröffentlichen wir innerhalb von 5 Werktagen einen Postmortem-Bericht (gemäß [/sla/](/sla/)). ## Stdio (npm) – für die lokale Entwicklung Das [`@astroway/mcp`](https://www.npmjs.com/package/@astroway/mcp)-Paket wird lokal als Subprozess ausgeführt. Ein npm-Paket, native Integration mit Claude Desktop, Cursor und jedem MCP-kompatiblen Client. ## Funktionsweise Die Tool-Liste wird **zum Zeitpunkt des Builds** aus der Live-OpenAPI-Spezifikation generiert ([api.astroway.info/v1/openapi.json](https://api.astroway.info/v1/openapi.json)). Jede neue Version des Pakets übernimmt automatisch alle neuen Endpunkte – es ist keine manuelle Pflege erforderlich. Jeder Endpunkt wird zu einem Tool der Form: - `tools/list` gibt Beschreibung und Eingabeschema (mit Beispiel-Anfragekörper) zurück - `tools/call` führt einen HTTP-POST auf `https://api.astroway.info/v1/` mit deinem `ASTROWAY_API_KEY` aus - Die Antwort wird dem Agenten als strukturiertes JSON zurückgegeben Jede Version wird zudem mit einer SLSA-Provenienz ausgeliefert ([Sigstore-bescheinigt](https://search.sigstore.dev/)) – dies garantiert, dass das npm-Paket tatsächlich aus dem Commit im öffentlichen Repository gebaut wurde. ## Installation ### Claude Desktop (macOS) Füge in `~/Library/Application Support/Claude/claude_desktop_config.json` hinzu: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` Starte Claude Desktop neu. In der Leiste unter dem Chat erscheint ein 🛠️-Symbol mit der Anzahl der geladenen Tools. ### Cursor Füge in `~/.cursor/mcp.json` hinzu: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` ### Cline / Continue / Windsurf / Copilot / VS Code MCP Der Befehl `npx @astroway/mcp` funktioniert in jedem MCP-kompatiblen Client. Die Konfiguration ist identisch – nur der Pfad zur Datei ändert sich: ```json { "mcpServers": { "astroway": { "command": "npx", "args": ["-y", "@astroway/mcp"], "env": { "ASTROWAY_API_KEY": "aw_live_..." } } } } ``` | Client | Pfad zur Konfiguration | |---|---| | **Cline** (VS Code) | `.cline/mcp.json` im Workspace-Root | | **Continue** | `~/.continue/config.json` (unter `mcpServers`) | | **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | | **GitHub Copilot Chat (VS Code)** | Preview-Flag → `mcp.json` im Workspace | | **VS Code MCP-Erweiterung** | `~/.vscode/mcp.json` | ### Andere MCP-Clients Starte als Stdio-Server: ```bash ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp ``` ## Datenschutz – ab v1.0.0+ Dieser MCP-Server **sendet nichts an AstroWay zurück**, außer den API-Aufrufen, die du ihm zur Ausführung gibst. Keine Telemetrie, kein Analytics, kein Opt-in/Opt-out-Schalter – standardmäßig keine Datenweitergabe. Ausgehende Anfragen enthalten zwei Identifikations-Header, damit der AstroWay-Backend den MCP-Verkehr von direkten HTTP-Aufrufen in den eigenen Logs unterscheiden kann: - `User-Agent: astroway-mcp/ (Node/)` - `X-Astroway-Channel: mcp` Keiner dieser Header enthält Session-IDs, Machine-Fingerprints oder andere persönliche Daten. Es handelt sich um die übliche `User-Agent`-Semantik – jedes CLI-Tool sendet ähnliche Informationen. ## Subset-Registrierung – ab v1.0.0+ Wenn du nur einen Teil des Katalogs nutzt, registriere eine Teilmenge, um das Kontextfenster des LLM kompakt zu halten: ```jsonc { "env": { "ASTROWAY_API_KEY": "aw_live_...", "ASTROWAY_TOOL_GROUPS": "western,vedic,relational", // nur diese Präfixe "ASTROWAY_READONLY": "1" // überspringe ai/horoscope/reports (LLM-basiert, verbrauchen Credits) } } ``` Häufig genutzte Gruppen: `western`, `vedic`, `tarot`, `numerology`, `hd` (Human Design), `relational` (Synastrie/Komposit/Davison), `prognostics` (Transite/Progressions/Rückkehr), `aspects`, `horary`, `geo`, `chinese`, `bazi`, `mayan`, `iching`, `runes`, `geomancy`. Führe `npx @astroway/mcp --list-tools` aus, um die vollständige Liste zu sehen. `ASTROWAY_READONLY=1` überspringt drei Gruppen, die intern den LLM aufrufen (`ai`, `horoscope`, `reports`) – nützlich, wenn du reine deterministische Kartenberechnungen ohne Credits-Verbrauch für Textgenerierung möchtest. ## Stabilitätsgarantie – ab v1.0.0+ - **Der Katalog ist für die Dauer der Sitzung eingefroren.** 624 Tools, 12 Prompts und 14 Ressourcen sind im veröffentlichten npm-Paket zum Zeitpunkt des Builds eingebettet – während der Verbindung ändert sich nichts. Wenn dein Client `tools/list` nach dem ersten Aufruf zwischenspeichert, bleibt es für die gesamte Sitzung korrekt. - **Tool-Bezeichner sind innerhalb einer Major-Version stabil.** Der Name unter `astroway__` wird innerhalb von `v1.x` nicht umbenannt oder entfernt, ohne einen Hinweis im `CHANGELOG.md` und eine parallele Verfügbarkeit für mindestens eine Minor-Version. - **Die Tool-Eingabeform ist innerhalb einer Minor-Version stabil.** Einschränkungen (Regex, Bereich, Enum) kommen in Patches; das Hinzufügen eines Pflichtfelds erfordert ein Minor-Update. - **Aktualisierung des Katalogs durch Neuinstallation.** `npm i -g @astroway/mcp@latest` (oder die `npx`-Form in deiner Konfiguration) lädt die aktuelle Tool-Liste beim nächsten Start. ## Beispiel-Prompts Nach dem Anschließen des Servers bitte den KI-Agenten: ### Geburtskarte > Berechne meine Geburtskarte – geboren am 15. März 1990, 14:30 Uhr, Kiew. Beschreibe Sonne, Mond, Aszendent und finde enge Aspekte. Claude ruft das `chart`-Tool mit deinen Parametern auf, erhält eine strukturierte JSON-Antwort und beschreibt die Karte in Worten. ### Transite > Welche bedeutenden Transite der langsamen Planeten werden im Jahr 2027 in meiner Geburtskarte auftreten? Claude führt zwei Tool-Aufrufe aus: zuerst `transits` (aktueller Snapshot), dann `transit-calendar` (Zeitraum). Er interpretiert die Trends. ### Vedic Mahadasha > Führe die Vimshottari Mahadasha für eine Person aus, die am 22.07.1985 um 06:45 Uhr in Mumbai geboren wurde. In welchem Zeitraum befindet sich diese Person gerade? Über das Tool `vedic/dashas/vimshottari/maha` – exakter UTC-Timestamp des aktuellen Zeitraums. ### Synastrie > Vergleiche zwei Karten: A – 10.06.1988 09:15 Uhr London, B – 22.11.1991 22:40 Uhr Berlin. Welche stärksten Kreuz-Aspekte gibt es? Das `synastry`-Tool mit zwei `chart`-Blöcken + Interpretation des Kompatibilitätswerts. ### Tarot > Ziehe 3 Karten nach Rider-Waite-Smith: Vergangenheit – Gegenwart – Zukunft. Frage: „Soll ich den neuen Job annehmen?“. Seed = 42. `tarot/rider-waite/spread` mit festem Seed für Reproduzierbarkeit. ## Liste aller Tools Nach dem Anschließen frage den KI-Agenten: > Liste alle AstroWay-Tools auf. Oder von der Kommandozeile: ```bash ASTROWAY_API_KEY=aw_test_smoke npx @astroway/mcp 2>&1 | head -1 # (startet den Stdio-Server; protokollierte Tool-List-Aufrufe kommen vom MCP-Client) ``` ## Konfiguration | Variable | Standardwert | Beschreibung | Ab Version | |---|---|---|---| | `ASTROWAY_API_KEY` | *(erforderlich)* | Live: `aw_live_…`. Sandbox: `aw_test_…`. | 0.1.0 | | `ASTROWAY_BASE_URL` | `https://api.astroway.info/v1` | Überschreibe für Self-Hosted/Staging-Umgebungen. | 0.1.0 | | `ASTROWAY_TOOL_GROUPS` | *(alle Gruppen)* | Komma-getrennte Präfixe zur Einschränkung des Katalogs (`western,vedic,relational`). | 1.0.0 | | `ASTROWAY_READONLY` | `0` | `1` überspringt LLM-basierte Gruppen (`ai`, `horoscope`, `reports`). | 1.0.0 | | `LOG_LEVEL` | `error` | `silent`/`error`/`warn`/`info`/`debug` – Log-Level für stderr. | 0.8.0 | | `LOG_FILE` | *(nicht geschrieben)* | Pfad zur Datei für das Duplizieren von Logs. | 0.8.0 | | `MCP_FLAT_TOOLS` | `0` | `1` gibt flache Namen vor v0.9 zurück (`chart` statt `astroway_western_chart`). Legacy. | 0.9.0 | ## Warum MCP und keine direkte Integration? Ein generischer LLM (ohne Grounding) würde sagen: *„Irgendwann im Juli bildet Saturn einen Trigon zu deinem Jupiter“* – ohne genaues Datum, mit einer Abweichung von ±15 Tagen. **Der MCP-Agent** führt einen `tool_use POST /v1/transits` aus und gibt einen UTC-Timestamp **bis auf die Sekunde genau** zurück, basierend auf dem Swiss Ephemeris. Der Vorteil liegt nicht im LLM, sondern in der **Garantie, dass die Berechnung korrekt** ist – nicht erfunden. ## Paket-Distribution - **mcp.so listing:** [mcp.so/server/astroway-mcp/astroway](https://mcp.so/server/astroway-mcp/astroway) - **mcpservers.org:** wartet auf Genehmigung (Stand Mai 2026) - **awesome-mcp-servers (punkpeye):** [PR #5972](https://github.com/punkpeye/awesome-mcp-servers/pull/5972) ## Links - 📦 npm: [npmjs.com/package/@astroway/mcp](https://www.npmjs.com/package/@astroway/mcp) - 📘 API-Dokumentation: [/docs/api/](/docs/api/) - 🔑 Registrierung: [/dashboard/sign-up](/dashboard/sign-up) - 💰 Preise: [/pricing/](/pricing/) - 🌐 Öffentliches Repository (MIT): [github.com/astroway/astroway-mcp](https://github.com/astroway/astroway-mcp)