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

ONEM 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é. Il lit une base de données embarquée, donc aucune connexion réseau au moment des requêtes — le même modèle auto-hébergé qu'agridata MCP et INS MCP.

Quels clients MCP sont supportés ?

Tout client compatible MCP : Claude Desktop, Claude Code, Cursor, VS Code 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 la configuration définit-elle PYTHONIOENCODING=utf-8 ?

Les données portent des libellés français accentués (énergie, redevance, …). Sous Windows en particulier, Python peut utiliser par défaut un encodage de console non-UTF-8 et planter sur ces caractères. Définir PYTHONIOENCODING=utf-8 dans la configuration du client l'évite. C'est sans effet sur macOS/Linux, donc à conserver partout.

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

Le logiciel est sous licence MIT. Les chiffres sont ceux de l'ONEM, restructurés pour un accès machine ; le projet est non officiel et attribue la source. Les conditions exactes de réutilisation sont celles de l'ONEM — consultez l'ONEM pour toute réutilisation au-delà de l'attribution.

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

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

Guide

Démarrer avec ONEM MCP en 20 minutes

Cloner ONEM MCP, l'installer en local dans un environnement virtuel Python, connecter votre client MCP et lancer une première vraie requête sur les statistiques énergétiques nationales de la Tunisie.

Résultat attendu

À la fin de ce guide, ONEM 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 chiffres énergétiques tunisiens avec leurs qualificateurs et leur provenance. Temps total estimé : 15 à 20 minutes si Python est déjà installé ; davantage s'il faut d'abord installer un runtime. Aucune étape de build : la base de données est livrée avec le dépôt.

Prérequis

Un client compatible MCP : Claude Desktop, Claude Code, Cursor, VS Code, ou le MCP Inspector.
Python 3.12 ou plus récent. Téléchargement sur python.org si non installé.
Aucun gestionnaire de paquets supplémentaire ni dépendance système. ONEM MCP installe deux wheels pip (duckdb, mcp) ; DuckDB ne nécessite aucun serveur.
Aucune connexion Internet au moment des requêtes. La base embarquée est lue localement ; le réseau n'est nécessaire qu'une fois, pour cloner le dépôt.

É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/onem-tunisia-mcp.git
cd onem-tunisia-mcp
python -m venv .venv
# macOS / Linux :
source .venv/bin/activate
# Windows (PowerShell) :
# .venv\Scripts\Activate.ps1
pip install duckdb mcp

Cela installe les deux dépendances d'exécution dans l'environnement virtuel. Aucune étape de build : la base énergétique extraite (energy.duckdb) est livrée avec le dépôt, donc le serveur fonctionne immédiatement.

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

Le Python de l'environnement virtuel est celui qui contient duckdb et mcp installés ; le client doit donc lancer cet interpréteur précis. Notez son chemin absolu :

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

Vous le collerez, avec le chemin absolu vers mcp_server.py, 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é onem-energy (à noter : pas le nom du dépôt). L'entrée PYTHONIOENCODING=utf-8 est requise — les données portent des libellés français accentués.

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": {
    "onem-energy": {
      "command": "/chemin/absolu/vers/onem-tunisia-mcp/.venv/bin/python",
      "args": ["/chemin/absolu/vers/onem-tunisia-mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Sauvegardez le fichier, puis redémarrez Claude Desktop.

Cursor, autres clients MCP stdio

La plupart des clients acceptent la même structure que Claude Desktop :

json

{
  "mcpServers": {
    "onem-energy": {
      "command": "/chemin/absolu/vers/onem-tunisia-mcp/.venv/bin/python",
      "args": ["/chemin/absolu/vers/onem-tunisia-mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

VS Code

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

json

{
  "servers": {
    "onem-energy": {
      "type": "stdio",
      "command": "/chemin/absolu/vers/onem-tunisia-mcp/.venv/bin/python",
      "args": ["/chemin/absolu/vers/onem-tunisia-mcp/mcp_server.py"],
      "env": { "PYTHONIOENCODING": "utf-8" }
    }
  }
}

Claude Code (CLI)

Une seule commande, sans fichier de configuration :

bash

claude mcp add onem-energy --env PYTHONIOENCODING=utf-8 -- /chemin/absolu/vers/onem-tunisia-mcp/.venv/bin/python /chemin/absolu/vers/onem-tunisia-mcp/mcp_server.py

Étape 4 — Premier appel de test

Dans le client, ouvrez une nouvelle conversation et demandez :

« Quels outils le serveur onem-energy expose-t-il ? »

Une réponse correcte liste les douze outils — parmi eux search_series, get_series, get_observation, compare, get_conflicts, convert_units et get_scope_glossary. Si cette liste apparaît, la connexion fonctionne.

Étape 5 — Première vraie requête

Essayez une question qui exerce la récupération attentive aux qualificateurs :

« Production de gaz naturel de la Tunisie, base PCI, annuelle, 2024. »

Le serveur renvoie la série avec calorific_basis: PCI et period_type: annual explicites, ainsi que la provenance au niveau de la cellule (édition source, page, tableau, cellule) — sans confusion PCI/PCS. Lui demander de comparer une série PCI à une série PCS renvoie refused_incompatible : le garde-fou, par conception.

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.
ModuleNotFoundError: duckdb (ou mcp) dans les logs du client. Le client a lancé un Python différent de celui où vous avez installé les dépendances. Pointez la configuration vers le chemin absolu de l'interpréteur de l'environnement virtuel.
Accents corrompus ou UnicodeEncodeError sous Windows. Ajoutez "env": { "PYTHONIOENCODING": "utf-8" } à la configuration du serveur (présent dans les snippets ci-dessus). Les données utilisent des libellés français accentués.
Une requête renvoie « out-of-scope ». Ce n'est pas un bug — certaines familles (prix, volumes d'échanges, raffinage, exploration) et éditions sont différées et signalées comme hors périmètre par conception, distinct de « aucune donnée n'existe ».
compare renvoie refused_incompatible. Garde-fou attendu : vous avez tenté de relier des séries incompatibles (PCI vs PCS, annuel vs cumul). Récupérez chaque série séparément, ou comparez des séries compatibles.
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
```
PYTHONIOENCODING=utf-8 npx @modelcontextprotocol/inspector /chemin/absolu/vers/onem-tunisia-mcp/.venv/bin/python /chemin/absolu/vers/onem-tunisia-mcp/mcp_server.py
```
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é ?: ONEM 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é. Il lit une base de données embarquée, donc aucune connexion réseau au moment des requêtes — le même modèle auto-hébergé qu'agridata MCP et INS MCP.
Quels clients MCP sont supportés ?: Tout client compatible MCP : Claude Desktop, Claude Code, Cursor, VS Code 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 la configuration définit-elle PYTHONIOENCODING=utf-8 ?: Les données portent des libellés français accentués (énergie, redevance, …). Sous Windows en particulier, Python peut utiliser par défaut un encodage de console non-UTF-8 et planter sur ces caractères. Définir PYTHONIOENCODING=utf-8 dans la configuration du client l'évite. C'est sans effet sur macOS/Linux, donc à conserver partout.
Les données sont-elles librement réutilisables ?: Le logiciel est sous licence MIT. Les chiffres sont ceux de l'ONEM, restructurés pour un accès machine ; le projet est non officiel et attribue la source. Les conditions exactes de réutilisation sont celles de l'ONEM — consultez l'ONEM pour toute réutilisation au-delà de l'attribution.
Où signaler un bug ou demander un jeu de données ?: Ouvrir une issue sur https://github.com/tanitdata/onem-tunisia-mcp ou écrire à contact@tanitdata.org.