Openzim MCP

🚀 OpenZIM MCP Server

OpenZIM MCP transforms static ZIM archives into dynamic knowledge engines for Large Language Models. It offers intelligent, structured access that LLMs need to effectively navigate and understand vast knowledge repositories.

🚀 Quick Start

Installation

# Install from PyPI (recommended)
pip install openzim-mcp

Development Installation

For contributors and developers:

# Clone the repository
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# Install dependencies
uv sync

# Install development dependencies
uv sync --dev

Prepare ZIM Files

Download ZIM files (e.g., Wikipedia, Wiktionary, etc.) from the Kiwix Library and place them in a directory:

mkdir ~/zim-files
# Download ZIM files to ~/zim-files/

Running the Server

# Using the console script (after pip install)
openzim-mcp /path/to/zim/files

# Or using the module
python -m openzim_mcp /path/to/zim/files

# For development (from source)
uv run python -m openzim_mcp /path/to/zim/files

# Or using make (development)
make run ZIM_DIR=/path/to/zim/files

MCP Configuration

Add to your MCP client configuration:

{
  "openzim-mcp": {
    "command": "openzim-mcp",
    "args": ["/path/to/zim/files"]
  }
}

Alternative configuration using Python module:

{
  "openzim-mcp": {
    "command": "python",
    "args": [
      "-m",
      "openzim_mcp",
      "/path/to/zim/files"
    ]
  }
}

For development (from source):

{
  "openzim-mcp": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/openzim-mcp",
      "run",
      "python",
      "-m",
      "openzim_mcp",
      "/path/to/zim/files"
    ]
  }
}

✨ Features

• 🔒 Security First: Comprehensive input validation and path traversal protection
• ⚡ High Performance: Intelligent caching and optimized ZIM file operations
• 🧠 Smart Retrieval: Automatic fallback from direct access to search-based retrieval for reliable entry access
• 🧪 Well Tested: 90%+ test coverage with comprehensive test suite
• 🏗️ Modern Architecture: Modular design with dependency injection
• 📝 Type Safe: Full type annotations throughout the codebase
• 🔧 Configurable: Flexible configuration with validation
• 📊 Observable: Structured logging and health monitoring

💻 Usage Examples

Basic Usage

# Install the package
pip install openzim-mcp

# Run the server
openzim-mcp /path/to/zim/files

Advanced Usage

{
  "name": "search_zim_file",
  "arguments": {
    "zim_file_path": "C:\\zim\\wikipedia_en_100_2025-08.zim",
    "query": "biology",
    "limit": 3
  }
}

📚 Documentation

Available Tools

list_zim_files - List all ZIM files in allowed directories

No parameters required.

search_zim_file - Search within ZIM file content

Required parameters:

• zim_file_path (string): Path to the ZIM file
• query (string): Search query term

Optional parameters:

• limit (integer, default: 10): Maximum number of results to return
• offset (integer, default: 0): Starting offset for results (for pagination)

get_zim_entry - Get detailed content of a specific entry in a ZIM file

Required parameters:

• zim_file_path (string): Path to the ZIM file
• entry_path (string): Entry path, e.g., 'A/Some_Article'

Optional parameters:

• max_content_length (integer, default: 100000, minimum: 1000): Maximum length of returned content

Smart Retrieval Features:

• Automatic Fallback: If direct path access fails, automatically searches for the entry and uses the exact path found
• Path Mapping Cache: Caches successful path mappings for improved performance on repeated access
• Enhanced Error Guidance: Provides clear guidance when entries cannot be found, suggesting alternative approaches
• Transparent Operation: Works seamlessly regardless of path encoding differences (spaces vs underscores, URL encoding, etc.)

get_zim_metadata - Get ZIM file metadata from M namespace entries

Required parameters:

• zim_file_path (string): Path to the ZIM file

Returns: JSON string containing ZIM metadata including entry counts, archive information, and metadata entries like title, description, language, creator, etc.

get_main_page - Get the main page entry from W namespace

Required parameters:

• zim_file_path (string): Path to the ZIM file

Returns: Main page content or information about the main page entry.

list_namespaces - List available namespaces and their entry counts

Required parameters:

• zim_file_path (string): Path to the ZIM file

Returns: JSON string containing namespace information with entry counts, descriptions, and sample entries for each namespace (C, M, W, X, etc.).

browse_namespace - Browse entries in a specific namespace with pagination

Required parameters:

• zim_file_path (string): Path to the ZIM file
• namespace (string): Namespace to browse (C, M, W, X, A, I, etc.)

Optional parameters:

• limit (integer, default: 50, range: 1-200): Maximum number of entries to return
• offset (integer, default: 0): Starting offset for pagination

Returns: JSON string containing namespace entries with titles, content previews, and pagination information.

search_with_filters - Search within ZIM file content with advanced filters

Required parameters:

• zim_file_path (string): Path to the ZIM file
• query (string): Search query term

Optional parameters:

• namespace (string): Optional namespace filter (C, M, W, X, etc.)
• content_type (string): Optional content type filter (text/html, text/plain, etc.)
• limit (integer, default: 10, range: 1-100): Maximum number of results to return
• offset (integer, default: 0): Starting offset for pagination

Returns: Filtered search results with namespace and content type information.

get_search_suggestions - Get search suggestions and auto-complete

Required parameters:

• zim_file_path (string): Path to the ZIM file
• partial_query (string): Partial search query (minimum 2 characters)

Optional parameters:

• limit (integer, default: 10, range: 1-50): Maximum number of suggestions to return

Returns: JSON string containing search suggestions based on article titles and content.

get_article_structure - Extract article structure and metadata

Required parameters:

• zim_file_path (string): Path to the ZIM file
• entry_path (string): Entry path, e.g., 'C/Some_Article'

Returns: JSON string containing article structure including headings, sections, metadata, and word count.

extract_article_links - Extract internal and external links from an article

Required parameters:

• zim_file_path (string): Path to the ZIM file
• entry_path (string): Entry path, e.g., 'C/Some_Article'

Returns: JSON string containing categorized links (internal, external, media) with titles and metadata.

get_server_health - Get server health and statistics

No parameters required.

Returns:

• Server status and performance metrics
• Cache statistics
• Configuration information
• Instance tracking information
• Conflict detection results

get_server_configuration - Get detailed server configuration

No parameters required.

Returns: Comprehensive server configuration including diagnostics, validation results, and conflict detection.

diagnose_server_state - Comprehensive server diagnostics

No parameters required.

Returns: Detailed diagnostic information including instance conflicts, configuration validation, file accessibility checks, and actionable recommendations.

resolve_server_conflicts - Identify and resolve server conflicts

No parameters required.

Returns: Results of conflict resolution including cleanup actions and recommendations.

🔧 Technical Details

ZIM Test Data Integration

OpenZIM MCP integrates with the official zim-testing-suite for comprehensive testing with real ZIM files:

# Download essential test files (basic testing)
make download-test-data

# Download all test files (comprehensive testing)
make download-test-data-all

# List available test files
make list-test-data

# Clean downloaded test data
make clean-test-data

The test data includes:

• Basic files: Small ZIM files for essential testing
• Real content: Actual Wikipedia/Wikibooks content for integration testing
• Invalid files: Malformed ZIM files for error handling testing
• Special cases: Embedded content, split files, and edge cases

Test files are automatically organized by category and priority level.

Code Quality

# Format code
make format

# Run linting
make lint

# Type checking
make type-check

# Run all checks
make check

Project Structure

openzim-mcp/
├── openzim_mcp/             # Main package
│   ├── __init__.py        # Package initialization
│   ├── __main__.py        # Module entry point
│   ├── main.py            # Main entry point
│   ├── server.py          # MCP server implementation
│   ├── config.py          # Configuration management
│   ├── security.py        # Security and validation
│   ├── cache.py           # Caching functionality
│   ├── content_processor.py # Content processing
│   ├── zim_operations.py  # ZIM file operations
│   ├── exceptions.py      # Custom exceptions
│   └── constants.py       # Application constants
├── tests/                 # Test suite
├── pyproject.toml        # Project configuration
├── Makefile              # Development commands
└── README.md             # This file

📄 License

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