Skip to main content
Glama
README.md
# 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

A3.7/5.0

Scored across 3 tools

Disambiguation4/5

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.

Naming Consistency5/5

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.

Tool Count4/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues