MCP 服务器

MCP Wikidata Server

Provides access to Wikidata for Large Language Models through the Model Context Protocol, offering tools for entity search, detailed retrieval, SPARQL queries, relation exploration, and property-based searches.

README

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