A modern, secure MCP server that enables AI models to access and search offline ZIM format knowledge bases, including Wikipedia and educational content archives with intelligent navigation and context-aware discovery.

Installation

PyPI

pip install openzim-mcp

From Source

git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
uv sync
uv sync --dev

Running the Server

# Simple mode (default)
openzim-mcp /path/to/zim/files
python -m openzim_mcp /path/to/zim/files

# Advanced mode
openzim-mcp --mode advanced /path/to/zim/files
python -m openzim_mcp --mode advanced /path/to/zim/files

Configuration

Simple Mode (Default)

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

Advanced Mode

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

Python Module

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

Development

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

Available Tools

Tool	Description
list_zim_files	List all ZIM files in allowed directories
search_zim_file	Search ZIM file content with query, limit, and offset parameters
get_zim_entry	Retrieve detailed content of a specific entry in a ZIM file with smart extraction and automatic fallback
get_zim_metadata	Retrieve ZIM file metadata from M namespace entries, including entry count and archive information
get_main_page	Retrieve the main page from the W namespace
list_namespaces	List available namespaces and entry counts
browse_namespace	Browse entries in a specific namespace with pagination
search_with_filters	Search ZIM file content with advanced filters for namespace and content type
get_search_suggestions	Get search suggestions and autocomplete for partial queries
get_article_structure	Extract article structure and metadata, including headings, sections, and word count
extract_article_links	Extract internal and external links from an article with categorization

Features

• Dual mode support: Choose between simple mode (1 intelligent natural language tool) or advanced mode (15 specialized tools)
• Security first: Comprehensive input validation and path traversal protection
• High performance: Intelligent caching and optimized ZIM file operations
• Smart extraction: Automatic fallback from direct access to search-based results
• Intelligent navigation: Browse by namespace (articles, metadata, media) instead of blind searching
• Context-aware discovery: Retrieve article structure, relationships, and metadata for deeper understanding
• Intelligent search: Advanced filtering, autocomplete suggestions, and relevance-ranked results
• Optimized performance: Cached operations and pagination prevent timeouts on massive archives
• Link mapping: Extract internal/external links to understand content relationships
• Well tested: 90%+ test coverage with comprehensive test suite

Usage Examples

Search for biology articles in a Wikipedia ZIM file

Retrieve the content of a specific Wikipedia article

Browse all articles in a specific namespace

Get search suggestions for partial queries

Extract article structure and headings

Notes

Requires ZIM files downloaded from Kiwix Library. Supports ZIM format with Zstandard compression. Integrates with the official zim-testing-suite for comprehensive testing. Works offline with Wikipedia, Wiktionary, and other educational content archives.