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

# Serveur Olostep MCP

> Offrez à tout client AI compatible MCP des outils de scraping web, de recherche, de crawling et de réponses AI en moins d’une minute

Le serveur Olostep MCP offre à tout client AI compatible MCP (Claude, Cursor, Windsurf, VS Code, Claude Code, etc.) 10 outils prêts à l'emploi pour le web en direct — scraping, recherche, réponses AI avec citations, tâches par lots, crawling de site et découverte d'URL.

<CardGroup cols={2}>
  <Card title="Scraper & extraire" icon="file-lines">
    Récupérez du markdown, HTML, JSON ou texte depuis n'importe quelle URL avec rendu JS optionnel
  </Card>

  <Card title="Réponses AI" icon="sparkles">
    Réponses basées sur le web avec sources et sortie structurée
  </Card>

  <Card title="Lot & crawl" icon="layer-group">
    Jusqu'à 10k URLs en parallèle, ou découvrez de manière autonome un site entier
  </Card>

  <Card title="Carte & recherche" icon="map">
    Trouvez chaque URL sur un site ou effectuez une recherche web basée sur un parseur
  </Card>
</CardGroup>

## Avant de commencer

Tu as besoin d'une clé API Olostep. Obtiens-en une depuis le [tableau de bord Olostep](https://www.olostep.com/dashboard/api-keys) — le niveau gratuit couvre l'utilisation personnelle.

## Choisir une méthode d'installation

Le chemin le plus rapide pour chaque client est le **point d'accès hébergé** à `https://mcp.olostep.com/mcp`. Pas d'installation, pas de Node, pas de Docker — il suffit de coller une URL et ta clé API.

Si tu as besoin de le faire fonctionner entièrement en local (utilisation hors ligne, proxy d'entreprise, réseau isolé), chaque client prend également en charge une installation **local stdio** via `npx`. Chaque section ci-dessous montre les deux.

<Note>
  **Point d'accès hébergé** utilise `Authorization: Bearer YOUR_API_KEY`. **Local stdio** utilise `OLOSTEP_API_KEY` comme variable d'environnement. Ne les mélange pas — le mauvais mode d'authentification est l'erreur d'intégration numéro 1.
</Note>

## Configuration du client

<Tabs>
  <Tab title="Cursor">
    **Installation en un clic (recommandée) :**

    <a href="cursor://anysphere.cursor-deeplink/mcp/install?name=olostep&config=eyJ1cmwiOiJodHRwczovL21jcC5vbG9zdGVwLmNvbS9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgWU9VUl9BUElfS0VZIn19">
      <img src="https://cursor.com/deeplink/mcp-install-dark.png" alt="Ajouter le serveur Olostep MCP à Cursor" style={{ maxHeight: 32 }} />
    </a>

    Remplace `YOUR_API_KEY` dans la configuration résultante par ta vraie clé.

    **Configuration manuelle :**

    Crée ou modifie `.cursor/mcp.json` à la racine de ton projet (ou `~/.cursor/mcp.json` pour une configuration globale) :

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

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

      Nécessite Node.js 18+ sur ta machine.
    </Accordion>

    **Vérification :** Ouvre Cursor → Paramètres → MCP. Tu devrais voir `olostep` listé avec **10 outils** incluant `scrape_website`. Si tu vois "Connecté, 0 outils", ta clé API est incorrecte.
  </Tab>

  <Tab title="Claude Code">
    **Installation CLI (recommandée) :**

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

    **Configuration manuelle :**

    Ajoute à ta configuration MCP Claude Code (`.mcp.json` à la racine du projet, ou `~/.claude.json` globalement) :

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

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

      Ou en JSON :

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

    **Vérification :** Exécute `/mcp` dans Claude Code. Tu devrais voir `olostep` connecté avec 10 outils.
  </Tab>

  <Tab title="Claude Desktop">
    **Emplacement du fichier de configuration :**

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

    **Hébergé (recommandé) :**

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

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

      Ou installe via Smithery :

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

    <Warning>
      Claude Desktop doit être **complètement quitté et relancé** pour que les changements de configuration prennent effet — fermer la fenêtre ne suffit pas (il reste actif dans la barre de menu / la barre système).
    </Warning>

    **Vérification :** Ouvre Claude Desktop → cherche l'icône 🔨 (marteau) dans le champ de saisie du chat. Clique dessus — tu devrais voir 10 outils Olostep listés.
  </Tab>

  <Tab title="VS Code">
    Le support MCP de VS Code est intégré à GitHub Copilot (mode Agent). Ajoute ceci à `.vscode/mcp.json` dans ton projet, ou à ton `settings.json` utilisateur :

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

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

    **Vérification :** Ouvre le panneau de chat Copilot → passe en mode Agent → le popover des outils devrait lister les outils Olostep.
  </Tab>

  <Tab title="Windsurf">
    Ajoute à `~/.codeium/windsurf/mcp_config.json` :

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

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

    **Vérification :** Cascade → Paramètres → MCP. `olostep` devrait apparaître avec 10 outils.
  </Tab>

  <Tab title="Docker">
    Si tu préfères exécuter le serveur dans un conteneur (CI, environnement isolé, pas de Node sur l'hôte) :

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

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

    Dans une configuration client MCP (stdio) :

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

    Prend en charge `linux/amd64` et `linux/arm64`. Source sur [GitHub](https://github.com/olostep/olostep-mcp-server).
  </Tab>

  <Tab title="Metorial">
    1. Ouvre le [tableau de bord Metorial](https://metorial.com)
    2. Navigue vers **MCP Servers**
    3. Recherche **Olostep**
    4. Clique sur **Install** et colle ta clé API

    Pour une configuration manuelle :

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

## Choisir le bon outil

Le serveur MCP expose 10 outils. Utilise cet arbre de décision pour choisir le bon — l'agent utilise le même raisonnement :

| Tu veux...                                      | Utilise                                   | Remarques                                                |
| ----------------------------------------------- | ----------------------------------------- | -------------------------------------------------------- |
| Le contenu d'une page spécifique                | `scrape_website` ou `get_webpage_content` | Défini `wait_before_scraping=2000–5000` pour les SPA     |
| Une réponse web en langage naturel avec sources | `answers`                                 | Retourne une synthèse AI + citations                     |
| Résultats de recherche pour une requête         | `search_web`                              | Basé sur un parseur, non AI, structuré                   |
| Une liste d'URLs sur un site                    | `create_map`                              | Découverte d'URL uniquement — ne scrape PAS              |
| URLs filtrées par requête                       | `get_website_urls`                        | Classées par pertinence pour ta `search_query`           |
| Plusieurs URLs connues à la fois                | `batch_scrape_urls` + `get_batch_results` | Asynchrone — démarre, puis interroge                     |
| Un site entier ou une section                   | `create_crawl` + `get_crawl_results`      | Asynchrone — suit les liens à partir d'une URL de départ |

<Tip>
  **Scraping d'un site entier ?** Utilise `create_crawl`, pas `batch_scrape_urls`. Crawl découvre ET scrape. Batch est pour une liste connue d'URLs que tu as déjà.
</Tip>

### Détails des outils

<Accordion title="scrape_website">
  Extrait le contenu d'une seule URL. Prend en charge `markdown`, `html`, `json`, `text`. `country` optionnel pour les requêtes géo-ciblées, `wait_before_scraping` (0–10000 ms) pour les sites lourds en JS, et `parser` (par exemple `@olostep/amazon-product`) pour une extraction structurée.
</Accordion>

<Accordion title="get_webpage_content">
  Version légère en markdown uniquement de `scrape_website`. À utiliser lorsque tu veux juste du markdown propre et que tu n'as pas besoin d'options de format.
</Accordion>

<Accordion title="search_web">
  Résultats de recherche web structurés (basés sur un parseur) pour une requête. `country` optionnel pour des résultats localisés. Retourne du JSON, pas de la prose AI.
</Accordion>

<Accordion title="answers">
  Réponse alimentée par AI à une `task` avec sources et citations. Passe un argument `json` pour obtenir la réponse dans une forme spécifique — soit un schéma JSON, soit une courte description en langage naturel.
</Accordion>

<Accordion title="batch_scrape_urls">
  Scraping asynchrone de 2 à 10k URLs que tu as déjà. Retourne un `batch_id` — puis appelle `get_batch_results` pour récupérer le contenu. Défini `wait_for_completion_seconds` (jusqu'à 900) si tu veux un seul appel bloquant au lieu de l'interrogation. Recommandé : 60 pour les lots de moins de 50 URLs, 300–600 pour 50–1k, 0 (interroger séparément) pour les lots plus grands.
</Accordion>

<Accordion title="get_batch_results">
  Récupère le statut et le contenu extrait pour un `batch_id`. Retourne `processing` jusqu'à ce que ce soit terminé, puis `completed` avec le tableau d'éléments.
</Accordion>

<Accordion title="create_crawl">
  Crawl asynchrone qui suit les liens à partir d'un `start_url`. Utilise `include_url_patterns` / `exclude_url_patterns` (syntaxe glob comme `/blog/**`) pour délimiter. Retourne un `crawl_id` — puis appelle `get_crawl_results`.
</Accordion>

<Accordion title="get_crawl_results">
  Récupère le statut et les pages pour un `crawl_id`. Prend en charge la pagination via `cursor` et `items_limit` (max 100 par appel). Retourne `in_progress` jusqu'à ce que ce soit terminé.
</Accordion>

<Accordion title="create_map">
  Obtiens une liste d'URLs sur un site. Découverte d'URL uniquement — ne scrape pas. À utiliser lorsque tu veux faire apparaître des URLs candidates (par exemple, laisser l'utilisateur choisir un sous-ensemble). Prend en charge `include_url_patterns` / `exclude_url_patterns` et `search_query`.
</Accordion>

<Accordion title="get_website_urls">
  Comme `create_map`, mais les URLs sont classées par pertinence pour une `search_query` requise. À utiliser lorsque tu veux les N meilleurs liens correspondants sur un site.
</Accordion>

## Dépannage

<Accordion title="Le serveur apparaît mais affiche 0 outils">
  Ta clé API est invalide ou limitée en taux. Ouvre le [tableau de bord des clés API](https://www.olostep.com/dashboard/api-keys) et vérifie la clé. Si tu utilises le point d'accès hébergé, l'en-tête doit être **exactement** `Authorization: Bearer sk_...` — pas de guillemets autour de la valeur, pas d'espaces supplémentaires.
</Accordion>

<Accordion title="`npx: command not found` ou `command not found: olostep-mcp`">
  Node.js n'est pas installé (ou pas dans ton PATH). Installe Node 18+ depuis [nodejs.org](https://nodejs.org/), puis redémarre ton terminal **et** ton client MCP. Sur Windows, passe à un CMD/PowerShell qui a Node dans le PATH.
</Accordion>

<Accordion title="Connexion refusée ou erreurs DNS sur `mcp.olostep.com`">
  Tu es probablement derrière un proxy d'entreprise ou un pare-feu bloquant l'hôte. Passe à l'installation local stdio (`npx -y olostep-mcp`) — elle effectue des requêtes sortantes vers `api.olostep.com` à la place, ce qui est généralement autorisé.
</Accordion>

<Accordion title="Configuration modifiée mais la liste des outils est obsolète">
  Le client a mis en cache l'ancienne configuration. Quitte complètement et relance — ne te contente pas de fermer la fenêtre. Claude Desktop en particulier continue de fonctionner dans la barre de menu / la barre système.
</Accordion>

<Accordion title="Échecs spécifiques à Windows avec `npx`">
  Si `npx` échoue à lancer le serveur sur Windows, utilise la forme encapsulée par CMD :

  ```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>`">
  Tu as atteint le point d'accès hébergé sans en-tête d'authentification (ou avec le mauvais format). Ajoute l'en-tête à la configuration de ton client exactement comme indiqué dans l'onglet de configuration.
</Accordion>

## Recettes

Copie-colle des invites qui fonctionnent bien avec les outils :

* **Scraper une liste d'URLs de produits :** *"J'ai un CSV de 200 URLs de produits Amazon. Scrape-les par lot avec `parser=@olostep/amazon-product` et retourne-les en JSON."*
* **Crawl un site de docs :** *"Crawl [https://stripe.com/docs](https://stripe.com/docs) avec `max_pages=50` et `include_url_patterns=['/docs/**']`. Résume chaque section en markdown."*
* **Trouver des concurrents :** *"Utilise `answers` pour trouver les 5 principaux concurrents de Notion pour les sites de documentation technique. Retourne le nom, la page d'accueil et le positionnement en une ligne."*
* **Cartographier puis scraper :** *"Exécute `create_map` sur [https://example.com](https://example.com) filtré sur `/blog/**`, puis `batch_scrape_urls` sur les 20 meilleurs résultats."*

## Source & versions

* [Dépôt GitHub](https://github.com/olostep/olostep-mcp-server)
* [Package npm](https://www.npmjs.com/package/olostep-mcp)
* [Docker Hub](https://hub.docker.com/r/olostep/mcp-server)
* [Registre MCP](https://registry.modelcontextprotocol.io/)