Headless Domains MCP-Server

Offizieller Model Context Protocol (MCP)-Server für Headless Domains. Dieser Server stellt Headless Domains API-Operationen für MCP-kompatible Clients wie Claude Desktop, Cursor und Windsurf bereit.

Funktionen

search_domain: Überprüfen, ob eine Domain verfügbar ist
lookup_whois: Eine registrierte Identität untersuchen
register_domain: Eine Domain mit einem API-Schlüssel registrieren
sync_bio: Agenten-/Profil-Bio-Inhalte mit einem API-Schlüssel synchronisieren
Automatische Transportauswahl:
- stdio für lokale MCP-Clients
- sse wenn PORT für gehostete Bereitstellungen vorhanden ist

Anforderungen

Python 3.10+
Optional: ein Headless Domains API-Schlüssel für authentifizierte Tools

Lokale Einrichtung

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Umgebungsvariablen

Variable	Erforderlich	Standard	Zweck
`HEADLESSDOMAINS_API_KEY`	Nein	nicht gesetzt	Sendet `X-API-Key` für authentifizierte Endpunkte
`HEADLESSDOMAINS_API_BASE_URL`	Nein	`https://headlessdomains.com/api/v1`	Überschreibt die API-Basis-URL
`HEADLESSDOMAINS_TIMEOUT`	Nein	`20`	HTTP-Timeout in Sekunden
`HEADLESSDOMAINS_REGISTER_PATH`	Nein	`/domains/register`	Überschreibt den Registrierungs-Endpunktpfad, falls sich die API ändert
`HEADLESSDOMAINS_SYNC_BIO_PATH`	Nein	`/domains/{domain}/bio`	Überschreibt den Sync-Bio-Endpunktpfad, falls sich die API ändert
`MCP_TRANSPORT`	Nein	auto	Erzwingt einen Transport wie `stdio` oder `sse`
`HOST`	Nein	`0.0.0.0`	Bind-Host für den SSE-Modus
`PORT`	Nein	nicht gesetzt	Wenn vorhanden, startet der Server im `sse`-Modus

Lokal ausführen

Für einen lokalen MCP-Client verwendet der Server standardmäßig stdio:

python server.py

Sie können ihn auch über das MCP CLI ausführen:

mcp run server.py

Claude Desktop Konfiguration

Fügen Sie einen Servereintrag zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "headlessdomains": {
      "command": "mcp",
      "args": [
        "run",
        "/absolute/path/to/headlessdomains-mcp/server.py"
      ],
      "env": {
        "HEADLESSDOMAINS_API_KEY": "your-api-key-here"
      }
    }
  }
}

Wenn Sie noch keine authentifizierten Tools benötigen, können Sie HEADLESSDOMAINS_API_KEY weglassen.

Gehosteter SSE-Modus

Wenn PORT vorhanden ist, startet server.py automatisch einen SSE-Transport:

PORT=8080 python server.py

Typischer Start im Railway-Stil:

HOST=0.0.0.0 PORT=8080 python server.py

Tool-Hinweise

`register_domain`

Erfordert HEADLESSDOMAINS_API_KEY
Sendet eine Basis-Payload mit domain, namespace, years, agreed_to_terms (true) und payment_method ("gems")
Akzeptiert extra_payload_json für API-Felder, die nicht fest im Tool codiert sind

Beispiel:

{
  "domain": "myagent.agent",
  "years": 1,
  "extra_payload_json": "{\"owner_email\":\"me@example.com\"}"
}

`sync_bio`

Erfordert HEADLESSDOMAINS_API_KEY
Synchronisiert mit dem /domains/<domain>/bio Endpunkt
Sendet domain, bio und bio_markdown
Akzeptiert extra_payload_json für alle zusätzlichen API-Felder (wie name, x, github usw.)

Beispiel:

{
  "domain": "myagent.agent",
  "bio_markdown": "# About Me",
  "extra_payload_json": "{\"name\":\"My Agent Name\", \"x\":\"twitter_handle\"}"
}

Docker

Build:

docker build -t headlessdomains-mcp .

Ausführen:

docker run --rm -p 8080:8080 \
  -e PORT=8080 \
  -e HEADLESSDOMAINS_API_KEY=your-api-key-here \
  headlessdomains-mcp

Rauchtests

Nach der Installation der Abhängigkeiten:

python -m py_compile server.py
python - <<'PY'
import server
print(server.search_domain("example.agent"))
print(server.lookup_whois("test.agent"))
PY

Hinweise

/temp-specs wird in .gitignore ignoriert, damit lokale Planungsdokumente nicht in der Versionskontrolle landen.

Headless Domains MCP Server