ipwho-mcp
# ipwho-mcp
Serveur MCP local pour [IP Who](https://www.ipwho.org/docs/gettingstarted/overview). Il interroge `https://api.ipwho.org` et expose trois outils : un contrôle de risque, la fiche d’une adresse, et un lookup groupé.
Le serveur parle MCP en stdio. La même commande sert à Cursor, Claude Code, Claude Desktop, Codex et l’application ChatGPT Desktop. ChatGPT sur le web n’est pas pris en charge.
La clé API est lue dans `IPWHO_API_KEY` et envoyée dans le header `Authorization: Bearer`. Elle n’est jamais placée dans l’URL.
## Prérequis
- Node.js 20 ou plus récent
- Une clé API IP Who. Le plan gratuit permet 2 000 requêtes par jour. Crée-la depuis la [page d’authentification](https://www.ipwho.org/docs/gettingstarted/authentication).
## Installation
```bash
npx -y ipwho-mcp install
```
La commande demande la clé si `IPWHO_API_KEY` n’est pas déjà définie, puis enregistre le serveur `ipwho` dans les configurations utilisateur qu’elle trouve :
| Client | Fichier |
| --- | --- |
| Cursor | `~/.cursor/mcp.json` |
| Claude Desktop | `claude_desktop_config.json` de la plateforme |
| Claude Code | `claude mcp add --scope user`, si la commande `claude` est présente |
| Codex et ChatGPT Desktop | `~/.codex/config.toml` |
Un client absent est ignoré. L’installeur ne modifie pas un `mcp.json` de projet. `--dry-run` liste les fichiers sans les écrire et sans afficher la clé.
```bash
npx -y ipwho-mcp install --dry-run
npx -y ipwho-mcp install --client cursor,codex
```
Tant que le paquet n’est pas publié sur npm, construis-le et lance l’installeur local. Il enregistre alors le chemin absolu de ce build :
```bash
npm install
npm run build
IPWHO_API_KEY=sk.xxx node dist/index.js install
```
`--npx` force la forme `npx -y ipwho-mcp`, à utiliser une fois le paquet publié.
Ensuite : redémarre Claude Desktop et ChatGPT Desktop, ouvre une nouvelle session Claude Code et Codex, puis recharge Cursor.
Le premier lancement via `npx` télécharge le paquet. Codex laisse 30 secondes à ce démarrage (`startup_timeout_sec`). Si Claude Code affiche un échec de connexion au premier essai, relance `claude mcp list` une fois le téléchargement fini.
## Outils
`check_ip` prend une adresse. Il ne demande que les blocs `security` et `connection`.
Le verdict :
- Tor et menace `high` : `block`
- VPN, Tor, menace `medium` ou `high`, ou menace inconnue : `challenge`
- sinon : `allow`
- un type de connexion `Corporate` ajoute l’indice `datacenter_or_office`. Il ne change pas le verdict.
- si le bloc `security` est absent : `challenge`
`lookup_ip` prend une adresse et, en option, `fields`, la liste des champs à conserver. Sans filtre, la fiche complète est renvoyée : géolocalisation, fuseau, drapeau, devise, connexion, sécurité.
`lookup_ips` prend de 1 à 50 adresses. Les doublons sont retirés. C’est un seul appel `GET /bulk/…`, donc une seule unité de quota. Si une adresse est invalide, aucune requête n’est envoyée.
Les trois outils sont en lecture seule. Une adresse est validée avant l’appel.
## Ce que le signal ne dit pas
`isThreat` vaut `low`, `medium` ou `high`. L’API ne fournit ni famille de malware, ni catégorie d’abus, ni score détaillé. Un VPN légitime produit `challenge`, pas une preuve d’attaque. Le plan gratuit est limité à 2 000 requêtes par jour et à 100 requêtes par seconde. Un HTTP 401 ou 429 ne doit pas être relancé en boucle.
## Configuration manuelle
Si tu préfères coller la configuration toi-même :
```json
{
"mcpServers": {
"ipwho": {
"type": "stdio",
"command": "npx",
"args": ["-y", "ipwho-mcp"],
"env": {
"IPWHO_API_KEY": "sk.xxx"
}
}
}
}
```
Pour Codex et ChatGPT Desktop, dans `~/.codex/config.toml` :
```toml
[mcp_servers.ipwho]
command = "npx"
args = ["-y", "ipwho-mcp"]
env = { IPWHO_API_KEY = "sk.xxx" }
startup_timeout_sec = 30
```
## Développement
```bash
npm test
npm run build
```
Les tests ne contactent pas l’API. Pour lancer le serveur à la main :
```bash
IPWHO_API_KEY=sk.xxx node dist/index.js
```
Sans argument, le process parle MCP sur stdin/stdout. Les journaux vont sur stderr.
TDQS
Scored across 3 tools
Les trois outils sont globalement distincts : lookup_ip renvoie les données brutes d'une IP, lookup_ips fait la même chose en lot, et check_ip produit un verdict décisionnel. La frontière entre check_ip et lookup_ip reste un peu floue puisque lookup_ip expose aussi les champs security (VPN, Tor, threat), mais les descriptions clarifient que seul check_ip rend un verdict allow/challenge/block.
Schéma verbe_nom entièrement cohérent en snake_case : check_ip, lookup_ip, lookup_ips. La distinction singulier/pluriel pour l'opération de lot est prévisible et lisible.
Trois outils pour un service d'intelligence IP, c'est mince mais chaque outil couvre un besoin réel : verdict, fiche unitaire, fiche en lot. On reste dans le périmètre bas de la fourchette recommandée sans outil redondant.
Le cycle lookup unitaire, lookup en lot et évaluation de risque est couvert, ce qui correspond au domaine. Petit manque : le verdict de risque n'existe pas en version lot (check_ip est mono-adresse), ce qu'un agent devra contourner par des appels répétés.