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

Related MCP server: FastDomainCheck MCP Server

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

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.