MCP Wikidata

🚀 MCP Wikidata Server

A Model Context Protocol (MCP) server that provides access to Wikidata for Large Language Models.

✨ Features

• 5 MCP tools for interacting with Wikidata:

  • search_entities: Text-based entity search
  • get_entity: Detailed retrieval of entities by ID
  • sparql_query: Execution of custom SPARQL queries
  • get_relations: Exploration of entity relations
  • find_by_property: Search by property-value

• Supported APIs:

  • Wikibase API (entity search and retrieval)
  • SPARQL Query Service (complex queries)
  • Multilingual support and intelligent caching

📦 Installation

1. Clone the project

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

2. Install dependencies

uv sync

3. Test the installation

uv run python test_connection.py

💻 Usage Examples

Basic Usage

# Example of using search_entities
{
  "query": "Einstein",
  "language": "en",
  "limit": 5,
  "type": "item"
}

# Example of using get_entity
{
  "entity_id": "Q937",
  "language": "en", 
  "simplified": true
}

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

# Example of using get_relations
{
  "entity_id": "Q937",
  "relation_type": "outgoing",
  "limit": 20
}

# Example of using find_by_property
{
  "property": "P106",
  "value": "physicist",
  "limit": 10
}

📚 Documentation

Configuration with Claude Desktop

Recommended Configuration (Portable)

Add this configuration to your Claude Desktop file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Important: Replace /path/to/your/mcp-wikidata/ with the absolute path to your installation directory.

Alternative with Direct uv

If you prefer a configuration without a wrapper script:

{
  "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"
      }
    }
  }
}

Advanced Configuration

Environment Variables

Create a .env file based on .env.example:

# User-Agent for API requests
WIKIDATA_USER_AGENT=MCP-Wikidata/0.1.0

# Request rate limit (per minute)
WIKIDATA_RATE_LIMIT=60

# Request timeout in seconds
WIKIDATA_TIMEOUT=30

# Cache TTL in seconds
WIKIDATA_CACHE_TTL=3600

# Maximum number of results per request
WIKIDATA_MAX_RESULTS=50

# Default language
WIKIDATA_DEFAULT_LANGUAGE=en

Debug Logs

To diagnose issues:

uv run mcp-wikidata --log-level DEBUG

Troubleshooting

"server disconnected" error in Claude Desktop

1. Check uv installation:

   which uv
   # Should return a path like /Users/username/.local/bin/uv
   

2. Test the wrapper script:

   ./run_mcp_wikidata.sh --help
   

3. Check permissions:

   chmod +x run_mcp_wikidata.sh
   

4. Restart Claude Desktop after modifying the configuration

"spawned uv ENOENT" error

This error indicates that Claude Desktop cannot find the uv command. The run_mcp_wikidata.sh wrapper script automatically resolves this issue by searching for uv in several common locations.

Diagnostic Logs

Detailed logs are available in:

• MCP Inspector console
• Claude Desktop log files (depending on your OS)
• MCP server stderr output

🔧 Technical Details

Project Structure

mcp-wikidata/
  ├ mcp_wikidata/           # Main package
     ├ __init__.py
     ├ server.py           # Main MCP server
     ├ config.py           # Configuration
     ├ tools.py            # Definitions of MCP tools
     └ wikidata_client.py  # Wikidata API client
  ├ tests/                  # Tests
  ├ run_mcp_wikidata.sh    # Wrapper script (recommended)
  ├ test_*.py              # Test scripts
  ├ pyproject.toml         # Project configuration
  ├ .env.example           # Environment variables
  └ README.md

🤝 Contribution

Contributions are welcome! Feel free to:

• Report bugs
• Propose improvements
• Add new MCP tools
• Enhance the documentation

📄 License

MIT License - see the LICENSE file for more details.

📚 Useful Resources

• MCP Documentation
• Wikidata API
• SPARQL Query Service
• uv Documentation

Generated with Claude Code 🚀