Utiliser Haloscan avec Claude Code (API et MCP)

Il y a deux façons de brancher Haloscan sur une IA. La première est le serveur MCP que Haloscan documente sur son site, conçu pour Claude Desktop. La seconde, que j’utilise au quotidien avec Claude Code, consiste à appeler directement l’API en curl. Cette page détaille la seconde avec les pièges que j’ai rencontrés, et résume la première sans prétendre l’avoir testée.

Existe-t-il un MCP Haloscan ?

Oui. Haloscan publie sur son site un guide d’installation du MCP Haloscan. Le guide précise que ce serveur a été « créé bénévolement pour la communauté SEO par Jérémy Santos ». Il est donc documenté par Haloscan, sans être présenté comme un produit maison. Le paquet s’appelle @occirank/haloscan-server. D’après le registre npm, il existe depuis mai 2025 et sa version la plus récente est la 2.0.28, mise à jour en septembre 2026.

Le guide vise Claude Desktop. Il faut Node.js, ajouter le serveur au fichier claude_desktop_config.json avec la variable HALOSCAN_API_KEY, puis redémarrer complètement l’application. Pour tester, il suggère de demander le solde de crédits, un appel qui ne consomme aucun crédit.

Pour Claude Code, la documentation MCP de Claude Code ajoute un serveur local avec claude mcp add. En croisant les deux documentations, la commande devrait être :

claude mcp add --env HALOSCAN_API_KEY=VOTRE_CLE --transport stdio haloscan \
  -- npx -y @occirank/haloscan-server start

Je ne l’ai pas testée : je n’utilise pas ce serveur. Vérifiez-la sur les deux pages citées avant de vous en servir.

Pourquoi j’appelle l’API directement

Claude Code exécute des commandes dans un terminal. Un appel curl lui suffit pour interroger Haloscan, et je garde le contrôle exact de ce qui part : endpoint, corps de la requête, nombre de lignes demandées. Les réponses arrivent en JSON brut, que je trie ensuite en local par volume, allintitle ou intention. Il n’y a aucun intermédiaire à installer ni à mettre à jour.

La clé reste dans un fichier .env lu par le script. Elle n’apparaît jamais dans la conversation avec l’IA, ni dans un fichier versionné.

Les deux pièges qui font échouer les premiers appels

1. Cloudflare rejette les bibliothèques HTTP de Python

Mes appels en Python (urllib, requests) ont été refusés avec une erreur Cloudflare 1010, quelle que soit la clé. Cloudflare explique cette erreur par un blocage fondé sur la « signature » du client. La solution qui marche : passer par curl avec un User-Agent de navigateur. En Python, j’appelle curl en sous-processus.

2. L’en-tête n’est pas Authorization

Un en-tête Authorization: Bearer renvoie une erreur 403. La clé passe dans un en-tête dédié, haloscan-api-key. Autre point : les adresses de l’application web (sans /api/ dans le chemin) fonctionnent par session et refusent la clé. L’API, c’est https://api.haloscan.com/api/, en POST avec un corps JSON.

Un exemple prêt à copier

Une petite fonction shell, avec une clé lue dans .env (remplacez le chemin par le vôtre) :

K=$(grep '^HALOSCAN_API_KEY=' ~/mon-projet/.env | cut -d= -f2-)
UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36"
hs(){ curl -s --max-time 30 -A "$UA" -H "haloscan-api-key: $K" \
      -H "Content-Type: application/json" -X POST \
      "https://api.haloscan.com/api/$1" -d "$2"; }

hs keywords/questions '{"keyword":"isolation combles","lineCount":200}'

Le même appel en Python, toujours via curl :

import json, subprocess

def haloscan(endpoint, corps, cle="VOTRE_CLE_API"):
    cmd = ["curl", "-sS", "--max-time", "90",
           "-A", "Mozilla/5.0 (Macintosh) Chrome/140.0",
           "-H", "haloscan-api-key: " + cle,
           "-H", "Content-Type: application/json",
           "-X", "POST", "--data", json.dumps(corps, ensure_ascii=False),
           "https://api.haloscan.com/api/" + endpoint]
    return json.loads(subprocess.run(cmd, capture_output=True, text=True).stdout)

r = haloscan("keywords/overview", {"keyword": "haloscan", "requested_data": ["metrics", "serp"]})

Pour contrôler la clé sans rien dépenser : GET https://api.haloscan.com/api/user/credit renvoie l’état de vos crédits et ne coûte rien.

Les endpoints que j’utilise

Chaque mot-clé arrive avec son volume, son CPC, la concurrence, le KGR, l’allintitle et des indicateurs d’intention (si_info, si_comm, si_trans, si_local, si_nav, si_brand). Pour domains/overview, les valeurs de requested_data qui fonctionnent sont metrics, best_pages, best_keywords et traffic_value.

Le piège le plus sournois : les valeurs ignorées sans erreur

Haloscan n’avertit pas quand une valeur de requested_data n’existe pas. Il l’ignore et répond normalement. Le 12 octobre, j’ai demandé keyword_metrics sur keywords/overview : la réponse contenait la SERP, aucune erreur, et pas une seule métrique. La bonne valeur est metrics. Sans requested_data, cet endpoint ne renvoie d’ailleurs presque rien d’utile.

La règle que j’applique : vérifier ce qui revient, ne rien supposer. Un champ absent ne veut pas dire « zéro ». De la même façon, un allintitle à « NA » ne veut pas dire « facile », comme je l’explique dans mon avis sur Haloscan après des mois d’usage.

D’autres routes m’ont renvoyé une erreur 500 avec les corps que j’ai essayés, notamment domains/keywords et domains/bulk. Je n’en conclus pas qu’elles sont cassées : le format attendu n’est probablement pas celui que j’ai envoyé.

Ma méthode pour un nouveau site

1. 3 à 5 requêtes de départ, chacune passée dans match, questions et related. On obtient plusieurs milliers de candidats avec leur volume, leur CPC et leur intention.
2. 3 concurrents passés dans domains/overview avec best_pages. On obtient l’arborescence qui leur rapporte du trafic. Avant de m’en inspirer, je divise leur trafic par leur nombre de pages actives. Sous 5 visites par page, ce n’est pas un modèle.
3. Le tri en local, par volume, KGR et intention, puis la lecture du top 10 réel de chaque sujet retenu, avec requested_data: ["serp"], avant d’écrire quoi que ce soit.

Claude Code enchaîne ces appels, consolide les fichiers JSON et prépare le tri. Je garde la décision sur les sujets et la relecture de ce qui est publié. C’est le principe de la stack IA que j’utilise chez SiteNova.

Combien de crédits cela consomme

Mon abonnement me donne, chaque mois, 10 000 recherches de mots-clés, 3 000 analyses de sites, 500 analyses en masse de chaque type et 700 000 lignes d’export. Ce sont exactement les quotas du plan Starter. Le 12 octobre, dix jours après le renouvellement, il m’en restait 9 717 côté mots-clés, alors que j’avais lancé une trentaine d’appels ce jour-là pour préparer des articles. Pour un éditeur qui travaille quelques sites français, la contrainte vient rarement des crédits. Elle vient du temps passé à lire les résultats.

À lire aussi : Haloscan : avis d’un utilisateur quotidien · Semrush gratuit : ce que permet le compte free · Comparatif des outils SEO que j’utilise