MCP — Verbindung mit Claude / Cursor

Der Model Context Protocol-Server von AstroWay exponiert alle 723 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 · npm: npmjs.com/package/@astroway/mcp · hosted: 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 (10.000 Credits/Monat kostenlos).

Cursor (One-Click)

Klicke auf den Button – Cursor öffnet sich, fragt nach Bestätigung und fügt den Eintrag automatisch hinzu:

In Cursor installieren →

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.
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).

Hinweis

Cursor setzt eine Begrenzung für die Länge von Namen: server_name:tool_name ≤ 60 Zeichen. Etwa 50 von 630 Tools (Gruppen hellenistic_brennan_*, psychological_modern_*, numerology_kabbalistic_strict_*) werden von Cursor gefiltert und sind über den LLM nicht verfügbar. Die restlichen ~580 funktionieren. Bei Claude Desktop gibt es diese Begrenzung nicht – hier steht der vollständige Katalog zur Verfügung.

Claude Desktop (UI-Flow)

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.

JSON-Konfiguration (manuell)

Für Cline / Continue / Windsurf oder ältere Versionen von Claude Desktop / Cursor:

{
  "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

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:

{
  "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. Bei Ausfällen von mehr als 5 Minuten veröffentlichen wir innerhalb von 5 Werktagen einen Postmortem-Bericht (gemäß /sla/).

Stdio (npm) – für die lokale Entwicklung

Das @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). 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/<path> 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) – 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:

{
  "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:

{
  "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:

{
  "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:

ASTROWAY_API_KEY=aw_live_... npx @astroway/mcp

Tipp

Hole dir deinen Schlüssel unter api.astroway.info/dashboard/sign-up. Der Free-Tarif umfasst 10 000 Credits/Monat, ohne Kreditkarte.

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/<version> (Node/<node-version>)
• 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:

{
  "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_<group>_<tool> 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:

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
• mcpservers.org: wartet auf Genehmigung (Stand Mai 2026)
• awesome-mcp-servers (punkpeye): PR #5972

Links

• 📦 npm: npmjs.com/package/@astroway/mcp
• 📘 API-Dokumentation: /docs/api/
• 🔑 Registrierung: /dashboard/sign-up
• 💰 Preise: /pricing/
• 🌐 Öffentliches Repository (MIT): github.com/astroway/astroway-mcp