Agent verbinden

Der MCP-Server von Astral ist lokal: Ihr Coding-Agent startet astral-mcp, das mit der geöffneten App spricht. Jeder der folgenden Clients braucht dasselbe, nämlich den Pfad zu dieser Binärdatei. astral-mcp setup schreibt ihn für Sie.

Bevor Sie anfangen

• Astral ist geöffnet, Developer mode und MCP sind aktiviert (Settings → Developer). Der Agent spricht mit der laufenden App; bei geschlossenem Astral meldet die Bridge einen Fehler.
• Kein API-Schlüssel und keine Umgebungsvariablen. Die Bridge authentifiziert sich zur Laufzeit mit einem Token vom lokalen Socket. setup schreibt nur den Pfad der Binärdatei und eine leere args-Liste.
• Die Binärdatei ist im Installationsprogramm enthalten. Unter macOS ist sie /Applications/Astral.app/Contents/MacOS/astral-mcp. Die Karte Connection unter Settings → Developer zeigt den genauen Pfad auf Ihrem Rechner. Die Installationspfade für Windows und Linux sind hier nicht dokumentiert, und der Windows-Build ist auf einem echten Rechner nicht verifiziert.
• Der Entwicklermodus ist auf macOS und Linux (X11) getestet und für Windows kompiliert, aber nicht verifiziert; siehe Plattformen.

Der Befehl setup

Führen Sie ihn mit dem vollständigen Pfad der Binärdatei aus (sie liegt nicht in Ihrem PATH), oder fügen Sie diesen Ordner dem PATH hinzu:

"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client <name> [--project [DIR] | --global] [--print] [--dry-run] [--instructions] [--binary PATH]
"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --client all-detected --dry-run
"/Applications/Astral.app/Contents/MacOS/astral-mcp" setup --list

In den folgenden Beispielen steht der Kürze halber astral-mcp.

Setup führt die Änderungen in die Datei ein, statt sie zu überschreiben: Andere Server und Schlüssel bleiben erhalten, nur der Eintrag astral ändert sich, eine Datei, in der er bereits stimmt, wird nicht angefasst, und eine vorhandene Datei wird zuvor nach <Datei>.astral-backup-<Zeitstempel> kopiert. Eine fehlerhafte Datei wird mit Zeile und Spalte gemeldet, und es wird nichts geschrieben. all-detected ist eine Heuristik: Ein Client gilt als installiert, wenn sein Konfigurationsordner existiert oder sein Befehl im PATH liegt.

Nach Client

• Claude Code
• Codex (CLI und IDE)
• VS Code und GitHub Copilot
• Cursor
• Windsurf
• Antigravity
• Gemini CLI
• JetBrains AI Assistant
• Orca
• OpenCode
• Jeder andere MCP-Client

Claude Code

astral-mcp setup --client claude-code --project .

Schreibt .mcp.json im Projekt. Ohne --project wird stattdessen der offizielle Befehl für den Benutzer-Scope ausgegeben, statt ~/.claude.json zu bearbeiten, das Claude Code in jeder Sitzung neu schreibt.

{
  "mcpServers": {
    "astral": {
      "type": "stdio",
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

# user scope, every project:
claude mcp add --scope user astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp

Claude Code fordert Sie auf, einen Projektserver aus .mcp.json zu genehmigen, wenn Sie claude dort zum ersten Mal starten.

Quelle: Claude Code: MCP.

Codex (CLI und IDE)

astral-mcp setup --client codex

Fügt [mcp_servers.astral] zu ~/.codex/config.toml (oder $CODEX_HOME/config.toml) hinzu und behält Kommentare und Formatierung bei. Mit --project wird .codex/config.toml geschrieben, die Codex nur in vertrauenswürdigen Projekten liest.

[mcp_servers.astral]
command = "/Applications/Astral.app/Contents/MacOS/astral-mcp"
args = []

Quelle: Codex: MCP.

VS Code und GitHub Copilot

astral-mcp setup --client vscode --project .

Schreibt .vscode/mcp.json, die VS Code und der Agent-Modus von Copilot lesen. Ohne --project wird ~/.copilot/mcp-config.json geschrieben (die globale Copilot-Datei, die auch GitHub Copilot CLI liest), die mcpServers statt servers verwendet.

{
  "servers": {
    "astral": {
      "type": "stdio",
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Starten Sie den Server über das CodeLens oberhalb davon in der Datei oder mit dem Befehl MCP: List Servers.

Quelle: VS Code: MCP configuration reference, VS Code: Add MCP servers.

Cursor

astral-mcp setup --client cursor

Schreibt ~/.cursor/mcp.json. Mit --project wird .cursor/mcp.json geschrieben.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Laden Sie die MCP-Server neu oder starten Sie Cursor neu, damit er sie übernimmt.

Quelle: Cursor: MCP.

Windsurf

astral-mcp setup --client windsurf

Schreibt ~/.codeium/windsurf/mcp_config.json. Windsurf hat keine MCP-Konfiguration pro Projekt.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Laden Sie die MCP-Server neu oder starten Sie Windsurf neu. Die Kanäle next und insiders verwenden andere Ordner (~/.codeium/windsurf-next, ~/.codeium/windsurf-insiders), in die setup nicht schreibt.

Quelle: Devin CLI: configuration import, VS Code: MCP configuration reference.

Antigravity

astral-mcp setup --client antigravity

Schreibt ~/.gemini/config/mcp_config.json. Mit --project wird .agents/mcp_config.json geschrieben.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Laden Sie die MCP-Server neu oder starten Sie Antigravity neu. Ältere Installationen verwendeten ~/.gemini/antigravity/mcp_config.json.

Quelle: Antigravity: MCP.

Gemini CLI

astral-mcp setup --client gemini-cli

Führt einen mcpServers-Eintrag in ~/.gemini/settings.json zusammen und behält den Rest Ihrer Einstellungen bei. Mit --project wird .gemini/settings.json geschrieben.

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Führen Sie /mcp in gemini aus, um es zu prüfen.

Quelle: Gemini CLI: MCP servers, Gemini CLI: configuration.

JetBrains AI Assistant

astral-mcp setup --client jetbrains --print

JetBrains speichert MCP-Server in den IDE-Einstellungen und nicht in einer dokumentierten Datei, daher gibt setup das JSON aus, statt es zu schreiben. Wählen Sie unter Settings | Tools | AI Assistant | Model Context Protocol (MCP) Add, dann JSON configuration, fügen Sie es ein und wählen Sie die Server-Ebene (global oder dieses Projekt).

{
  "mcpServers": {
    "astral": {
      "command": "/Applications/Astral.app/Contents/MacOS/astral-mcp",
      "args": []
    }
  }
}

Quelle: JetBrains: AI Assistant MCP.

Orca

astral-mcp setup --client orca --print

Orca führt andere Agenten aus (Claude Code, Codex und so weiter) und reicht die unter Settings → Integrations → MCP registrierten MCP-Server an sie weiter. Registrieren Sie dort den Pfad von astral-mcp, oder richten Sie den Agenten ein, den Sie in Orca ausführen, zum Beispiel --client claude-code --project <worktree>.

# Settings → Integrations → MCP → command:
/Applications/Astral.app/Contents/MacOS/astral-mcp

Quelle: Orca docs.

OpenCode

astral-mcp setup unterstützt OpenCode nicht, konfigurieren Sie es daher von Hand. Die Dokumentation von OpenCode beschreibt einen lokalen Server als einen Befehl, den es über stdio startet. Die neueste Dokumentation (V2) fügt einen über das Terminal hinzu:

opencode mcp add astral -- /Applications/Astral.app/Contents/MacOS/astral-mcp
opencode mcp list

Mit --global steht er in jedem Projekt zur Verfügung; ohne diese Option landet der Server in der Konfiguration des Projekts. Von Hand in opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "astral": {
        "type": "local",
        "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"]
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "astral": {
      "type": "local",
      "command": ["/Applications/Astral.app/Contents/MacOS/astral-mcp"],
      "enabled": true
    }
  }
}

Quelle: OpenCode: MCP servers (V2) und die Seite zu V1. Nicht mit einem laufenden OpenCode getestet.

Jeder andere MCP-Client

Der Server von Astral ist ein standardmäßiger stdio-MCP-Server. Registrieren Sie in jedem Client, der einen solchen starten kann:

Die meisten Clients nehmen das als JSON mit einem command und einer args-Liste entgegen, wie in den Snippets oben. Den Dateinamen und den Schlüssel der obersten Ebene finden Sie auf der MCP-Seite Ihres Clients.

Prüfen, ob es funktioniert

Starten Sie bei geöffnetem Astral und aktiviertem Entwicklermodus die MCP-Server des Agenten neu oder laden Sie sie neu und fragen Sie:

Liste die Tools auf, die du vom MCP-Server von Astral hast.

Sie sollten die Tools aus der Tool-Referenz sehen. Für einen Aufruf, der die App berührt, bitten Sie den Agenten, in Ihrem Projekt test_list auszuführen: Er gibt Ihre gespeicherten Tests zurück oder eine leere Liste. In Gemini CLI zeigt /mcp den Server und seinen Status.

Wenn er nicht erscheint

• Stellen Sie sicher, dass Astral läuft und Developer → MCP aktiviert ist, und laden Sie dann die MCP-Server des Clients neu.
• Führen Sie astral-mcp setup --list aus, um zu sehen, wo die Datei jedes Clients liegt und ob er erkannt wurde.
• Führen Sie denselben Befehl mit --dry-run aus, um zu sehen, was sich ändern würde, oder mit --print für das Snippet.
• Setup erneut auszuführen ist unbedenklich: Es ändert nichts, wenn der Eintrag bereits stimmt.
• Fügen Sie --instructions hinzu, damit der Agent auch die kurze Astral-Anleitung in AGENTS.md erhält.