Wikidata MCP Server - Optimized Hybrid Architecture

A Model Context Protocol (MCP) server with Server-Sent Events (SSE) transport that connects Large Language Models to Wikidata's structured knowledge base. Features an optimized hybrid architecture that balances speed, accuracy, and verifiability by using fast basic tools for simple queries and advanced orchestration only for complex temporal/relational queries.

Architecture Highlights

• 🚀 Fast Basic Tools: 140-250ms for simple entity/property searches

• 🧠 Advanced Orchestration: 1-11s for complex temporal queries (when needed)

• ⚡ 50x Performance Difference: Empirically measured and optimized

• 🔄 Hybrid Approach: Right tool for each query type

• 🛡️ Graceful Degradation: Works with or without Vector DB API key

MCP Tools

Basic Tools (Fast & Reliable)

• search_wikidata_entity: Find entities by name (140-250ms)

• search_wikidata_property: Find properties by name (~200ms)

• get_wikidata_metadata: Entity labels, descriptions (~200ms)

• get_wikidata_properties: All entity properties (~200ms)

• execute_wikidata_sparql: Direct SPARQL queries (~200ms)

Advanced Tool (Complex Queries)

• query_wikidata_complex: Temporal/relational queries (1-11s)

  • ✅ "last 3 popes", "recent presidents of France"

  • ❌ Simple entity searches (use basic tools instead)

Live Demo

The server is deployed and accessible at:

• URL: https://wikidata-mcp-mirror.onrender.com

• MCP Endpoint: https://wikidata-mcp-mirror.onrender.com/mcp

• Health Check: https://wikidata-mcp-mirror.onrender.com/health

Usage with Claude Desktop

To use this server with Claude Desktop:

1. Install mcp-remote (if not already installed):

   npm install -g @modelcontextprotocol/mcp-remote

2. Edit the Claude Desktop configuration file located at:

   ~/Library/Application Support/Claude/claude_desktop_config.json

3. Configure it to use the remote MCP server:

   { "mcpServers": { "Wikidata MCP": { "command": "npx", "args": [ "mcp-remote", "https://wikidata-mcp-mirror.onrender.com/mcp" ] } } }

4. Restart Claude Desktop

5. When using Claude, you can now access Wikidata knowledge through the configured MCP server.

Deployment

Deploying to Render

1. Create a new Web Service in your Render dashboard

2. Connect your GitHub repository

3. Configure the service:

   • Build Command: pip install -e .

   • Start Command: python -m wikidata_mcp.api

4. Set Environment Variables:

   • Add all variables from .env.example

   • For production, set DEBUG=false

   • Make sure to set a proper WIKIDATA_VECTORDB_API_KEY

5. Deploy

The service will be available at https://your-service-name.onrender.com

Environment Setup

Prerequisites

• Python 3.10+

• Virtual environment tool (venv, conda, etc.)

• Vector DB API key (for enhanced semantic search)

Environment Variables

Create a .env file in the project root with the following variables:

2. Create and activate a virtual environment:

   python -m venv venv source venv/bin/activate # On Windows: .\venv\Scripts\activate

3. Install the required dependencies:

   pip install -e .

4. Create a .env file based on .env.example and configure your environment variables:

   cp .env.example .env # Edit .env with your configuration

5. Run the application:

   # Development python -m wikidata_mcp.api # Production (with Gunicorn) gunicorn --bind 0.0.0.0:8000 --workers 4 --timeout 120 --keep-alive 5 --worker-class uvicorn.workers.UvicornWorker wikidata_mcp.api:app

   The server will start on http://localhost:8000 by default with the following endpoints:

   • GET /health - Health check

   • GET /messages/ - SSE endpoint for MCP communication

   • GET /docs - Interactive API documentation (if enabled)

   • GET /metrics - Prometheus metrics (if enabled)

Environment Variables

Running with Docker

1. Build the Docker image:

   docker build -t wikidata-mcp .

2. Run the container:

   docker run -p 8000:8000 --env-file .env wikidata-mcp

Running with Docker Compose

1. Start the application:

   docker-compose up --build

2. For production, use the production compose file:

   docker-compose -f docker-compose.prod.yml up --build -d

Monitoring

The service exposes Prometheus metrics at /metrics when the PROMETHEUS_METRICS environment variable is set to true.

Health Check

Metrics

Testing

Running Tests

Run the test suite with:

Integration Tests

To test the Vector DB integration, you'll need to set the WIKIDATA_VECTORDB_API_KEY environment variable:

Test Client

You can also test the server using the included test client:

Or manually with curl:

Deployment on Render.com

This server is configured for deployment on Render.com using the render.yaml file.

Deployment Configuration

• Build Command: pip install -r requirements.txt

• Start Command: gunicorn -k uvicorn.workers.UvicornWorker server_sse:app

• Environment Variables:

  • PORT: 10000

• Health Check Path: /health

Docker Support

The repository includes a Dockerfile that's used by Render.com for containerized deployment. This allows the server to run in a consistent environment with all dependencies properly installed.

How to Deploy

1. Fork or clone this repository to your GitHub account

2. Create a new Web Service on Render.com

3. Connect your GitHub repository

4. Render will automatically detect the render.yaml file and configure the deployment

5. Click "Create Web Service"

After deployment, you can access your server at the URL provided by Render.com.

Architecture

The server is built using:

• FastAPI: For handling HTTP requests and routing

• SSE Transport: For bidirectional communication with clients

• MCP Framework: For implementing the Model Context Protocol

• Wikidata API: For accessing Wikidata's knowledge base

Key Components

• server_sse.py: Main server implementation with SSE transport

• wikidata_api.py: Functions for interacting with Wikidata's API and SPARQL endpoint

• requirements.txt: Dependencies for the project

• Dockerfile: Container configuration for Docker deployment on Render

• render.yaml: Configuration for deployment on Render.com

• test_mcp_client.py: Test client for verifying server functionality

Available MCP Tools

The server provides the following MCP tools:

• search_wikidata_entity: Search for entities by name

• search_wikidata_property: Search for properties by name

• get_wikidata_metadata: Get entity metadata (label, description)

• get_wikidata_properties: Get all properties for an entity

• execute_wikidata_sparql: Execute a SPARQL query

• find_entity_facts: Search for an entity and find its facts

• get_related_entities: Find entities related to a given entity

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Based on the Model Context Protocol (MCP) specification

• Uses Wikidata as the knowledge source

• Inspired by the MCP examples from the official documentation