Pourquoi le serveur tourne-t-il en local plutôt que sur un endpoint hébergé ?

INS MCP s'exécute comme un sous-processus local lancé par votre client MCP via stdio ; il n'y a pas de point d'accès hébergé. Les données étant publiques, l'intérêt est la façade locale sur le portail — aucun serveur à exploiter ou sécuriser. C'est l'architecture MCP standard, le même modèle qu'agridata MCP.

Quels clients MCP sont supportés ?

Tout client compatible MCP : Claude Desktop, Claude Code, Cursor, VS Code (mode agent Copilot), Cline/Roo Code, Windsurf et le MCP Inspector. Le format du fichier de configuration varie légèrement selon le client ; la commande de lancement est la même.

Pourquoi pip et un environnement virtuel, et non uv ?

INS MCP utilise un simple environnement virtuel Python et « pip install -e . » — aucun outil supplémentaire à installer, et compatible avec tout Python 3.10 ou plus récent. (Le serveur jumeau agridata MCP utilise uv ; INS garde volontairement une chaîne d'outils minimale.)

Les données sont-elles librement réutilisables ?

Oui. Les données suivent les conditions d'utilisation de l'INS (de type attribution, compatible CC-BY / ODC-BY, usage commercial autorisé) ; l'attribution est obligatoire et chaque réponse intègre un bloc d'attribution à reproduire. Il s'agit des conditions d'utilisation de l'INS — et non de la LNDPO qui régit agridata.

Où signaler un bug ou demander un jeu de données ?

Ouvrir une issue sur https://github.com/tanitdata/ins-tunisia-mcp ou écrire à contact@tanitdata.org.

Guide

Démarrer avec INS MCP en 20 minutes

Cloner INS MCP, l'installer en local dans un environnement virtuel Python, connecter votre client MCP et lancer une première vraie requête sur le portail de statistiques nationales de l'INS.

Résultat attendu

À la fin de ce guide, INS MCP tourne sur votre machine, votre client MCP habituel sait l'appeler, et vous avez exécuté une première requête qui renvoie des statistiques officielles tunisiennes avec une attribution de source. Temps total estimé : 15 à 20 minutes si Python est déjà installé ; comptez une dizaine de minutes supplémentaires sinon.

Prérequis

Un client compatible MCP : Claude Desktop, Claude Code, Cursor, VS Code (mode agent Copilot), Cline/Roo Code, Windsurf, ou le MCP Inspector.
Python 3.10 ou plus récent. Téléchargement sur python.org si non installé.
Aucun gestionnaire de paquets supplémentaire. INS MCP s'installe avec venv et pip de la bibliothèque standard — pas d'étape uv ni de lockfile.
Une connexion Internet pour cloner le dépôt et atteindre dataportal.ins.tn au moment des requêtes.

Étape 1 — Cloner, créer un environnement virtuel et installer

Choisir un répertoire qui hébergera le serveur, puis :

bash

git clone https://github.com/tanitdata/ins-tunisia-mcp.git
cd ins-tunisia-mcp
python -m venv .venv
# macOS / Linux :
source .venv/bin/activate
# Windows (PowerShell) :
# .venv\Scripts\Activate.ps1
pip install -e .

pip install -e . résout et installe toutes les dépendances déclarées dans pyproject.toml dans l'environnement virtuel. Sur un clone tout neuf, l'opération prend généralement moins d'une minute.

Étape 2 — Noter le chemin absolu du Python de l'environnement virtuel

Contrairement à un interpréteur global, le Python de l'environnement virtuel est celui qui contient INS MCP installé — le client doit donc lancer cet interpréteur précis. Notez son chemin absolu :

macOS / Linux : /chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python
Windows : C:\chemin\absolu\vers\ins-tunisia-mcp\.venv\Scripts\python.exe

Vous le collerez à la place de /chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python dans les snippets ci-dessous. Utiliser un simple python est la cause la plus fréquente d'une connexion qui échoue — voir Dépannage.

Étape 3 — Configurer le client MCP

Choisissez le snippet correspondant à votre client. Le serveur s'enregistre sous la clé ins ; seul le format du fichier change selon le client.

Claude Desktop

Fichier de configuration :

Windows : %APPDATA%\Claude\claude_desktop_config.json
macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

json

{
  "mcpServers": {
    "ins": {
      "command": "/chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python",
      "args": ["-m", "ins_mcp"]
    }
  }
}

Sauvegardez le fichier, puis redémarrez Claude Desktop.

Cursor, Windsurf, autres clients MCP stdio

La plupart des clients acceptent la même structure que Claude Desktop. Ajoutez le snippet au fichier de configuration MCP du client — Cursor utilise .cursor/mcp.json (projet) ou ~/.cursor/mcp.json (global) ; Windsurf utilise ~/.codeium/windsurf/mcp_config.json — puis rechargez et activez le serveur dans les réglages du client :

json

{
  "mcpServers": {
    "ins": {
      "command": "/chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python",
      "args": ["-m", "ins_mcp"]
    }
  }
}

VS Code (mode agent Copilot)

VS Code utilise une clé servers avec un type explicite :

json

{
  "servers": {
    "ins": {
      "type": "stdio",
      "command": "/chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python",
      "args": ["-m", "ins_mcp"]
    }
  }
}

Claude Code (CLI)

Une seule commande, sans fichier de configuration :

bash

claude mcp add ins -- /chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python -m ins_mcp

Étape 4 — Premier appel de test

Dans le client, ouvrez une nouvelle conversation et demandez :

« Quels outils sont exposés par le serveur ins ? »

Une réponse correcte liste les sept outils : ins_list_sources, ins_search_sources, ins_get_source, ins_get_dimension_elements, ins_get_data, ins_get_availability et ins_refresh_catalogue. Si cette liste apparaît, la connexion fonctionne.

Étape 5 — Première vraie requête

Essayez une question qui enchaîne recherche → exploration → récupération :

« Montre le PIB de la Tunisie aux prix du marché de 2014 à 2017. »

Le serveur résout le code de l'indicateur, récupère les observations et renvoie quatre valeurs annuelles (80 865,5 ; 84 689,2 ; 89 792,2 ; 96 324,7 millions de dinars) issues du cube « Principaux agrégats », chacune accompagnée d'un bloc d'attribution créditant le portail de données de l'INS. Au tout premier appel, le serveur amorce un catalogue local (quelques secondes) ; c'est ponctuel.

Dépannage

Le client signale qu'il ne trouve pas le serveur ou n'arrive pas à le lancer. La valeur command doit être le chemin absolu du Python de l'environnement virtuel (…/.venv/bin/python, ou …\.venv\Scripts\python.exe sous Windows), pas un simple python. Un interpréteur global n'a pas ins_mcp installé.
« command not found » / erreur de lancement dans les logs MCP du client. Les clients graphiques n'héritent souvent pas du PATH de votre shell ; ni python ni le script ins-mcp ne sont garantis trouvables. Utilisez toujours le chemin absolu du Python de l'environnement virtuel dans la configuration.
Le premier appel est lent, ou has_data semble incorrect juste après l'installation. Comportement attendu : le catalogue s'amorce à la première utilisation (~2 à 4 secondes) et une sonde en arrière-plan finit de marquer les cubes au cours de la minute ou deux suivantes. Aucune action nécessaire ; cela se complète tout seul.
Un cube attendu est absent. Demandez à l'assistant d'exécuter ins_refresh_catalogue pour re-télécharger le catalogue depuis le portail en direct — les cubes nouvellement publiés apparaissent après un rafraîchissement.
Une source est listée mais toute requête ne renvoie aucune observation. Vérifiez has_data sur la source : 10 des 78 cubes de l'INS (certains croisements du recensement 2014) sont des coquilles publiées-mais-vides, marquées has_data: false. C'est une réelle absence de données de l'INS, pas un bug. (Une fenêtre de dates sans fréquence renvoie une erreur frequency_required — fournissez annual ou quarterly.)
Vous voulez vérifier que le serveur démarre, avant même de le brancher à un client. Depuis le répertoire du clone, exécuter :
bash
```
npx @modelcontextprotocol/inspector /chemin/absolu/vers/ins-tunisia-mcp/.venv/bin/python -m ins_mcp
```
MCP Inspector s'ouvre dans le navigateur et permet d'appeler les outils sans client LLM.

La suite

Une fois le serveur opérationnel côté client, parcourez l'index Recherche pour des cas d'usage avancés. Pour transmettre un retour, signaler un bug ou proposer une collaboration, le dépôt GitHub et la page Contribuer sont les points d'entrée.

Questions fréquentes

Pourquoi le serveur tourne-t-il en local plutôt que sur un endpoint hébergé ?: INS MCP s'exécute comme un sous-processus local lancé par votre client MCP via stdio ; il n'y a pas de point d'accès hébergé. Les données étant publiques, l'intérêt est la façade locale sur le portail — aucun serveur à exploiter ou sécuriser. C'est l'architecture MCP standard, le même modèle qu'agridata MCP.
Quels clients MCP sont supportés ?: Tout client compatible MCP : Claude Desktop, Claude Code, Cursor, VS Code (mode agent Copilot), Cline/Roo Code, Windsurf et le MCP Inspector. Le format du fichier de configuration varie légèrement selon le client ; la commande de lancement est la même.
Pourquoi pip et un environnement virtuel, et non uv ?: INS MCP utilise un simple environnement virtuel Python et « pip install -e . » — aucun outil supplémentaire à installer, et compatible avec tout Python 3.10 ou plus récent. (Le serveur jumeau agridata MCP utilise uv ; INS garde volontairement une chaîne d'outils minimale.)
Les données sont-elles librement réutilisables ?: Oui. Les données suivent les conditions d'utilisation de l'INS (de type attribution, compatible CC-BY / ODC-BY, usage commercial autorisé) ; l'attribution est obligatoire et chaque réponse intègre un bloc d'attribution à reproduire. Il s'agit des conditions d'utilisation de l'INS — et non de la LNDPO qui régit agridata.
Où signaler un bug ou demander un jeu de données ?: Ouvrir une issue sur https://github.com/tanitdata/ins-tunisia-mcp ou écrire à contact@tanitdata.org.