MCP Wikidata Server

Un serveur Model Context Protocol (MCP) qui fournit un accès aux données Wikidata pour les Large Language Models.

🔧 Fonctionnalités

5 outils MCP pour interagir avec Wikidata :
- search_entities : Recherche textuelle d'entités
- get_entity : Récupération détaillée d'entités par ID
- sparql_query : Exécution de requêtes SPARQL personnalisées
- get_relations : Exploration des relations d'entités
- find_by_property : Recherche par propriété-valeur
APIs supportées :
- Wikibase API (recherche et récupération d'entités)
- SPARQL Query Service (requêtes complexes)
- Support multilingue et cache intelligent

📋 Prérequis

Python 3.10+
uv (gestionnaire de paquets Python moderne)

📦 Installation

1. Cloner le projet

git clone https://github.com/joelgombin/mcp-wikidata.git
cd mcp-wikidata

2. Installer les dépendances

uv sync

3. Tester l'installation

uv run python test_connection.py

⚙️ Configuration avec Claude Desktop

Configuration recommandée (portable)

Ajoutez cette configuration à votre fichier Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json sur macOS) :

{
  "mcpServers": {
    "mcp-wikidata": {
      "command": "/path/to/your/mcp-wikidata/run_mcp_wikidata.sh",
      "args": []
    }
  }
}

Important : Remplacez /path/to/your/mcp-wikidata/ par le chemin absolu vers votre dossier d'installation.

Alternative avec uv direct

Si vous préférez une configuration sans script wrapper :

{
  "mcpServers": {
    "mcp-wikidata": {
      "command": "uv",
      "args": ["run", "mcp-wikidata"],
      "cwd": "/path/to/your/mcp-wikidata",
      "env": {
        "PATH": "/usr/local/bin:/usr/bin:/bin:~/.local/bin"
      }
    }
  }
}

🧪 Tests et vérification

Test avec MCP Inspector

npx @modelcontextprotocol/inspector uv run mcp-wikidata

Tests manuels des APIs

uv run python test_manual.py

Test client MCP complet

uv run python test_mcp_client.py

🔧 Utilisation des outils

search_entities

Recherche d'entités par texte :

{
  "query": "Einstein",
  "language": "en",
  "limit": 5,
  "type": "item"
}

get_entity

Récupération d'entité par ID :

{
  "entity_id": "Q937",
  "language": "en", 
  "simplified": true
}

sparql_query

Requête SPARQL personnalisée :

{
  "query": "SELECT ?item ?itemLabel WHERE { ?item wdt:P31 wd:Q5 . SERVICE wikibase:label { bd:serviceParam wikibase:language \"en\" . } } LIMIT 10",
  "format": "json"
}

get_relations

Relations d'une entité :

{
  "entity_id": "Q937",
  "relation_type": "outgoing",
  "limit": 20
}

find_by_property

Recherche par propriété :

{
  "property": "P106",
  "value": "physicist",
  "limit": 10
}

⚙️ Configuration avancée

Variables d'environnement

Créez un fichier .env basé sur .env.example :

# User-Agent pour les requêtes API
WIKIDATA_USER_AGENT=MCP-Wikidata/0.1.0

# Limitation du taux de requêtes (par minute)
WIKIDATA_RATE_LIMIT=60

# Timeout des requêtes en secondes
WIKIDATA_TIMEOUT=30

# TTL du cache en secondes
WIKIDATA_CACHE_TTL=3600

# Nombre maximum de résultats par requête
WIKIDATA_MAX_RESULTS=50

# Langue par défaut
WIKIDATA_DEFAULT_LANGUAGE=en

Logs de debug

Pour diagnostiquer des problèmes :

uv run mcp-wikidata --log-level DEBUG

🔧 Dépannage

Erreur "server disconnected" dans Claude Desktop

Vérifiez l'installation d'uv :

which uv
# Doit retourner un chemin comme /Users/username/.local/bin/uv

Testez le script wrapper :
```
./run_mcp_wikidata.sh --help
```
Vérifiez les permissions :
```
chmod +x run_mcp_wikidata.sh
```
Redémarrez Claude Desktop après modification de la configuration

Erreur "spawned uv ENOENT"

Cette erreur indique que Claude Desktop ne trouve pas la commande uv. Le script wrapper run_mcp_wikidata.sh résout automatiquement ce problème en cherchant uv dans plusieurs emplacements courants.

Logs de diagnostic

Les logs détaillés sont disponibles dans :

Console de MCP Inspector
Fichiers de log Claude Desktop (selon votre OS)
Sortie stderr du serveur MCP

📁 Structure du projet

mcp-wikidata/
  ├ mcp_wikidata/           # Package principal
     ├ __init__.py
     ├ server.py           # Serveur MCP principal
     ├ config.py           # Configuration
     ├ tools.py            # Définitions des outils MCP
     └ wikidata_client.py  # Client API Wikidata
  ├ tests/                  # Tests
  ├ run_mcp_wikidata.sh    # Script wrapper (recommandé)
  ├ test_*.py              # Scripts de test
  ├ pyproject.toml         # Configuration du projet
  ├ .env.example           # Variables d'environnement
  └ README.md

🤝 Contribution

Les contributions sont bienvenues ! N'hésitez pas à :

Signaler des bugs
Proposer des améliorations
Ajouter de nouveaux outils MCP
Améliorer la documentation

📄 Licence

MIT License - voir le fichier LICENSE pour plus de détails.

📚 Ressources utiles

Généré avec Claude Code 🚀