> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Olostep MCP Server

> Gib jedem MCP-kompatiblen KI-Client Web-Scraping, Suche, Crawling und KI-Antwort-Tools in weniger als einer Minute

Der Olostep MCP-Server bietet jedem MCP-kompatiblen KI-Client (Claude, Cursor, Windsurf, VS Code, Claude Code, etc.) 10 einsatzbereite Tools für das Live-Web – Scraping, Suche, KI-Antworten mit Zitaten, Batch-Jobs, Site-Crawling und URL-Entdeckung.

<CardGroup cols={2}>
  <Card title="Scrape & extrahieren" icon="file-lines">
    Ziehe Markdown, HTML, JSON oder Text von jeder URL mit optionalem JS-Rendering
  </Card>

  <Card title="KI-Antworten" icon="sparkles">
    Web-basierte Antworten mit Quellen und strukturiertem Output
  </Card>

  <Card title="Batch & Crawl" icon="layer-group">
    Bis zu 10.000 URLs parallel oder autonom eine ganze Seite entdecken
  </Card>

  <Card title="Karte & Suche" icon="map">
    Finde jede URL auf einer Seite oder führe parserbasierte Websuche durch
  </Card>
</CardGroup>

## Bevor du anfängst

Du benötigst einen Olostep API-Schlüssel. Hol dir einen vom [Olostep-Dashboard](https://www.olostep.com/dashboard/api-keys) – die kostenlose Stufe deckt die persönliche Nutzung ab.

## Wähle einen Einrichtungsweg

Der schnellste Weg für jeden Client ist der **gehostete Endpunkt** unter `https://mcp.olostep.com/mcp`. Keine Installationen, kein Node, kein Docker – einfach eine URL und deinen API-Schlüssel einfügen.

Wenn du es vollständig lokal (Offline-Nutzung, Unternehmensproxy, luftdicht) ausführen musst, unterstützt jeder Client auch eine **lokale stdio**-Installation über `npx`. Jeder Abschnitt unten zeigt beides.

<Note>
  **Gehosteter Endpunkt** verwendet `Authorization: Bearer YOUR_API_KEY`. **Lokale stdio** verwendet `OLOSTEP_API_KEY` als Umgebungsvariable. Verwechsle sie nicht – der falsche Auth-Modus ist der häufigste Onboarding-Fehler.
</Note>

## Client-Einrichtung

<Tabs>
  <Tab title="Cursor">
    **Ein-Klick-Installation (empfohlen):**

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=olostep&config=eyJ1cmwiOiJodHRwczovL21jcC5vbG9zdGVwLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19">
      <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="Füge Olostep MCP Server zu Cursor hinzu" style={{ maxHeight: 32 }} />
    </a>

    Ersetze `YOUR_API_KEY` in der resultierenden Konfiguration durch deinen echten Schlüssel.

    **Manuelle Einrichtung:**

    Erstelle oder bearbeite `.cursor/mcp.json` in deinem Projektverzeichnis (oder `~/.cursor/mcp.json` für global):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Lokale stdio-Installation (optional)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      Erfordert Node.js 18+ auf deinem Rechner.
    </Accordion>

    **Verifizieren:** Öffne Cursor → Einstellungen → MCP. Du solltest `olostep` mit **10 Tools** einschließlich `scrape_website` sehen. Wenn du "Connected, 0 tools" siehst, ist dein API-Schlüssel falsch.
  </Tab>

  <Tab title="Claude Code">
    **CLI-Installation (empfohlen):**

    ```bash theme={null}
    claude mcp add --transport http olostep https://mcp.olostep.com/mcp \
      --header "Authorization: Bearer YOUR_API_KEY"
    ```

    **Manuelle Einrichtung:**

    Füge zu deiner Claude Code MCP-Konfiguration hinzu (`.mcp.json` im Projektverzeichnis oder `~/.claude.json` global):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Lokale stdio-Installation (optional)">
      ```bash theme={null}
      claude mcp add --transport stdio --env OLOSTEP_API_KEY=YOUR_API_KEY olostep \
        -- npx -y olostep-mcp
      ```

      Oder als JSON:

      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verifizieren:** Führe `/mcp` in Claude Code aus. Du solltest `olostep` mit 10 Tools verbunden sehen.
  </Tab>

  <Tab title="Claude Desktop">
    **Konfigurationsdatei-Speicherort:**

    | OS      | Pfad                                                              |
    | ------- | ----------------------------------------------------------------- |
    | macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
    | Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |
    | Linux   | `~/.config/Claude/claude_desktop_config.json`                     |

    **Gehostet (empfohlen):**

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Lokale stdio-Installation (optional)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```

      Oder Installation über Smithery:

      ```bash theme={null}
      npx -y @smithery/cli install @olostep/olostep-mcp-server --client claude
      ```
    </Accordion>

    <Warning>
      Claude Desktop muss **vollständig beendet und neu gestartet** werden, damit Konfigurationsänderungen wirksam werden – das Schließen des Fensters reicht nicht aus (es bleibt in der Menüleiste/Systemleiste aktiv).
    </Warning>

    **Verifizieren:** Öffne Claude Desktop → suche nach dem 🔨 (Hammer)-Symbol im Chat-Eingabefeld. Klicke darauf – du solltest 10 Olostep-Tools aufgelistet sehen.
  </Tab>

  <Tab title="VS Code">
    Die MCP-Unterstützung von VS Code ist in GitHub Copilot (Agent-Modus) integriert. Füge dies zu `.vscode/mcp.json` in deinem Projekt oder deinen Benutzer `settings.json` hinzu:

    ```json theme={null}
    {
      "servers": {
        "olostep": {
          "type": "http",
          "url": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Lokale stdio-Installation (optional)">
      ```json theme={null}
      {
        "servers": {
          "olostep": {
            "type": "stdio",
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verifizieren:** Öffne das Copilot-Chat-Panel → wechsle in den Agent-Modus → das Tool-Popover sollte Olostep-Tools auflisten.
  </Tab>

  <Tab title="Windsurf">
    Füge zu `~/.codeium/windsurf/mcp_config.json` hinzu:

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "serverUrl": "https://mcp.olostep.com/mcp",
          "headers": {
            "Authorization": "Bearer YOUR_API_KEY"
          }
        }
      }
    }
    ```

    <Accordion title="Lokale stdio-Installation (optional)">
      ```json theme={null}
      {
        "mcpServers": {
          "olostep": {
            "command": "npx",
            "args": ["-y", "olostep-mcp"],
            "env": {
              "OLOSTEP_API_KEY": "YOUR_API_KEY"
            }
          }
        }
      }
      ```
    </Accordion>

    **Verifizieren:** Cascade → Einstellungen → MCP. `olostep` sollte mit 10 Tools erscheinen.
  </Tab>

  <Tab title="Docker">
    Wenn du den Server lieber in einem Container ausführen möchtest (CI, isolierte Umgebung, kein Node auf dem Host):

    ```bash theme={null}
    docker pull olostep/mcp-server

    docker run -i --rm \
      -e OLOSTEP_API_KEY="YOUR_API_KEY" \
      olostep/mcp-server
    ```

    In einer MCP-Client-Konfiguration (stdio):

    ```json theme={null}
    {
      "mcpServers": {
        "olostep": {
          "command": "docker",
          "args": [
            "run", "-i", "--rm",
            "-e", "OLOSTEP_API_KEY=YOUR_API_KEY",
            "olostep/mcp-server"
          ]
        }
      }
    }
    ```

    Unterstützt `linux/amd64` und `linux/arm64`. Quelle auf [GitHub](https://github.com/olostep/olostep-mcp-server).
  </Tab>

  <Tab title="Metorial">
    1. Öffne das [Metorial-Dashboard](https://metorial.com)
    2. Navigiere zu **MCP Servers**
    3. Suche nach **Olostep**
    4. Klicke auf **Installieren** und füge deinen API-Schlüssel ein

    Für manuelle Konfiguration:

    ```json theme={null}
    {
      "olostep": {
        "command": "npx",
        "args": ["-y", "olostep-mcp"],
        "env": {
          "OLOSTEP_API_KEY": "YOUR_API_KEY"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Das richtige Tool auswählen

Der MCP-Server bietet 10 Tools. Verwende diesen Entscheidungsbaum, um das richtige auszuwählen – der Agent verwendet die gleiche Logik:

| Du möchtest...                            | Verwende                                    | Hinweise                                        |
| ----------------------------------------- | ------------------------------------------- | ----------------------------------------------- |
| Den Inhalt einer bestimmten Seite         | `scrape_website` oder `get_webpage_content` | Setze `wait_before_scraping=2000–5000` für SPAs |
| Eine natürliche Sprachantwort mit Quellen | `answers`                                   | Gibt KI-Synthese + Zitate zurück                |
| Suchergebnisse für eine Abfrage           | `search_web`                                | Parser-basiert, nicht KI, strukturiert          |
| Eine Liste von URLs auf einer Seite       | `create_map`                                | Nur URL-Entdeckung – kein Scraping              |
| URLs gefiltert nach Abfrage               | `get_website_urls`                          | Nach Relevanz zu deiner `search_query` gerankt  |
| Viele bekannte URLs auf einmal            | `batch_scrape_urls` + `get_batch_results`   | Asynchron – startet, dann abfragen              |
| Eine ganze Seite oder Abschnitt           | `create_crawl` + `get_crawl_results`        | Asynchron – folgt Links von einer Start-URL     |

<Tip>
  **Eine ganze Seite scrapen?** Verwende `create_crawl`, nicht `batch_scrape_urls`. Crawl entdeckt UND scrapet. Batch ist für eine bekannte Liste von URLs, die du bereits hast.
</Tip>

### Tool-Details

<Accordion title="scrape_website">
  Extrahiere Inhalte von einer einzelnen URL. Unterstützt `markdown`, `html`, `json`, `text`. Optional `country` für geo-targetierte Anfragen, `wait_before_scraping` (0–10000 ms) für JS-lastige Seiten und `parser` (z.B. `@olostep/amazon-product`) für strukturierte Extraktion.
</Accordion>

<Accordion title="get_webpage_content">
  Leichte Markdown-Only-Version von `scrape_website`. Verwende es, wenn du nur sauberes Markdown möchtest und keine Formatoptionen benötigst.
</Accordion>

<Accordion title="search_web">
  Strukturierte (parser-basierte) Websuchergebnisse für eine Abfrage. Optional `country` für lokalisierte Ergebnisse. Gibt JSON zurück, kein KI-Prosa.
</Accordion>

<Accordion title="answers">
  KI-gestützte Antwort auf eine `task` mit Quellen und Zitaten. Übergebe ein `json`-Argument, um die Antwort in einer bestimmten Form zu erhalten – entweder ein JSON-Schema oder eine kurze natürliche Sprachbeschreibung.
</Accordion>

<Accordion title="batch_scrape_urls">
  Asynchrones Scraping von 2–10k URLs, die du bereits hast. Gibt eine `batch_id` zurück – dann `get_batch_results` aufrufen, um Inhalte abzurufen. Setze `wait_for_completion_seconds` (bis zu 900), wenn du einen einzigen blockierenden Aufruf anstelle von Abfragen möchtest. Empfohlen: 60 für Batches unter 50 URLs, 300–600 für 50–1k, 0 (separat abfragen) für größere Batches.
</Accordion>

<Accordion title="get_batch_results">
  Holt den Status und die gescrapten Inhalte für eine `batch_id`. Gibt `processing` zurück, bis abgeschlossen, dann `completed` mit dem Items-Array.
</Accordion>

<Accordion title="create_crawl">
  Asynchrones Crawling, das Links von einer `start_url` folgt. Verwende `include_url_patterns` / `exclude_url_patterns` (Glob-Syntax wie `/blog/**`), um den Umfang festzulegen. Gibt eine `crawl_id` zurück – dann `get_crawl_results` aufrufen.
</Accordion>

<Accordion title="get_crawl_results">
  Holt den Status und die Seiten für eine `crawl_id`. Unterstützt Paginierung über `cursor` und `items_limit` (max. 100 pro Aufruf). Gibt `in_progress` zurück, bis abgeschlossen.
</Accordion>

<Accordion title="create_map">
  Erhalte eine Liste von URLs auf einer Seite. Nur URL-Entdeckung – kein Scraping. Verwende es, wenn du Kandidaten-URLs anzeigen möchtest (z.B. den Benutzer eine Teilmenge auswählen lassen). Unterstützt `include_url_patterns` / `exclude_url_patterns` und `search_query`.
</Accordion>

<Accordion title="get_website_urls">
  Wie `create_map`, aber URLs werden nach Relevanz zu einer erforderlichen `search_query` gerankt. Verwende es, wenn du die Top-N passenden Links auf einer Seite möchtest.
</Accordion>

## Fehlerbehebung

<Accordion title="Server erscheint, zeigt aber 0 Tools">
  Dein API-Schlüssel ist ungültig oder rate-limitiert. Öffne das [API-Schlüssel-Dashboard](https://www.olostep.com/dashboard/api-keys) und überprüfe den Schlüssel. Wenn du den gehosteten Endpunkt verwendest, muss der Header **genau** `Authorization: Bearer sk_...` sein – keine Anführungszeichen um den Wert, keine zusätzlichen Leerzeichen.
</Accordion>

<Accordion title="`npx: command not found` oder `command not found: olostep-mcp`">
  Node.js ist nicht installiert (oder nicht in deinem PATH). Installiere Node 18+ von [nodejs.org](https://nodejs.org/), dann starte dein Terminal **und** deinen MCP-Client neu. Unter Windows wechsle zu einem CMD/PowerShell, das Node im PATH hat.
</Accordion>

<Accordion title="Verbindung abgelehnt oder DNS-Fehler bei `mcp.olostep.com`">
  Du befindest dich wahrscheinlich hinter einem Unternehmensproxy oder einer Firewall, die den Host blockiert. Wechsle zur lokalen stdio-Installation (`npx -y olostep-mcp`) – sie stellt ausgehende Anfragen an `api.olostep.com`, was normalerweise erlaubt ist.
</Accordion>

<Accordion title="Bearbeitete Konfiguration, aber die Tool-Liste ist veraltet">
  Der Client hat die alte Konfiguration zwischengespeichert. Vollständig beenden und neu starten – nicht nur das Fenster schließen. Claude Desktop bleibt insbesondere in der Menüleiste/Systemleiste aktiv.
</Accordion>

<Accordion title="Windows-spezifische `npx`-Fehler">
  Wenn `npx` beim Starten des Servers unter Windows Fehler ausgibt, verwende die CMD-umwickelte Form:

  ```json theme={null}
  {
    "command": "cmd",
    "args": ["/c", "npx", "-y", "olostep-mcp"],
    "env": { "OLOSTEP_API_KEY": "YOUR_API_KEY" }
  }
  ```
</Accordion>

<Accordion title="`401 Missing Authorization: Bearer <OLOSTEP_API_KEY>`">
  Du hast den gehosteten Endpunkt ohne Auth-Header (oder mit dem falschen Format) aufgerufen. Füge den Header zu deiner Client-Konfiguration genau so hinzu, wie im Einrichtungs-Tab gezeigt.
</Accordion>

## Rezepte

Copy-Paste-Prompts, die gut mit den Tools funktionieren:

* **Eine Liste von Produkt-URLs scrapen:** *"Ich habe eine CSV mit 200 Amazon-Produkt-URLs. Scrape sie im Batch mit `parser=@olostep/amazon-product` und gib sie als JSON zurück."*
* **Eine Dokumentationsseite crawlen:** *"Crawl [https://stripe.com/docs](https://stripe.com/docs) mit `max_pages=50` und `include_url_patterns=['/docs/**']`. Fasse jeden Abschnitt als Markdown zusammen."*
* **Wettbewerber finden:** *"Verwende `answers`, um die Top 5 Wettbewerber von Notion für technische Dokumentationsseiten zu finden. Gib Name, Homepage und 1-Zeilen-Positionierung zurück."*
* **Karte erstellen und dann scrapen:** *"Führe `create_map` auf [https://example.com](https://example.com) gefiltert auf `/blog/**` aus, dann `batch_scrape_urls` auf den Top 20 Ergebnissen."*

## Quelle & Versionen

* [GitHub-Repo](https://github.com/olostep/olostep-mcp-server)
* [npm-Paket](https://www.npmjs.com/package/olostep-mcp)
* [Docker Hub](https://hub.docker.com/r/olostep/mcp-server)
* [MCP-Registry](https://registry.modelcontextprotocol.io/)