home / mcp / openzim mcp server

OpenZIM MCP Server

Transforms ZIM archives into structured, offline knowledge engines for AI models with mode options, smart retrieval, and high-performance access.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "cameronrye-openzim-mcp": {
      "command": "openzim-mcp",
      "args": [
        "/path/to/zim/files"
      ],
      "env": {
        "OPENZIM_MCP_SERVER_NAME": "openzim-mcp",
        "OPENZIM_MCP_CACHE__ENABLED": "true",
        "OPENZIM_MCP_LOGGING__LEVEL": "INFO",
        "OPENZIM_MCP_CACHE__MAX_SIZE": "100",
        "OPENZIM_MCP_CACHE__TTL_SECONDS": "3600",
        "OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH": "100000"
      }
    }
  }
}

OpenZIM MCP Server transforms static ZIM archives into a dynamic knowledge engine for AI models. By exposing structured access to offline content, it enables efficient querying, navigation, and extraction of articles, metadata, and embedded media for multi-agent AI workflows without requiring internet access.

How to use

You can run the OpenZIM MCP Server with a local ZIM archive directory and then connect your MCP client to it to perform smart queries, article lookups, metadata retrieval, and content extraction. Start in simple mode for a single intelligent tool or switch to advanced mode to enable all 18 specialized tools. Use the server to power research assistants, knowledge chatbots, and content analysis systems that operate offline.

How to install

Prerequisites: you need Python and/or Node.js tooling available on your system, plus access to ZIM files you want to index. Choose your preferred installation path from the options below.

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

# Development installation (from source)
# Clone the repository
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp

# Install dependencies (example commands shown; adapt to your environment)
uv sync
uv sync --dev

# Optional: install with make targets
``````},{

Additional sections

Configuration, security, and usage notes help you run and maintain your MCP server effectively.

Configuration and server management details are provided to help you tune caching, content limits, logging, and health monitoring. You can run integrity checks, diagnose server state, and resolve conflicts when multiple server instances operate on shared directories.

Available tools

list_zim_files

List all ZIM files in allowed directories with basic metadata.

search_zim_file

Search within ZIM file content for a query, with optional limit and offset for pagination.

get_zim_entry

Get detailed content of a specific ZIM entry by its path, with optional maximum content length and smart retrieval fallback.

get_zim_metadata

Retrieve ZIM file metadata including counts and archive information.

get_main_page

Fetch the main page entry from the W namespace of a ZIM file.

list_namespaces

List available namespaces with entry counts and sample entries.

browse_namespace

Browse entries within a specific namespace with pagination support.

search_with_filters

Search content with optional namespace and content-type filters.

get_search_suggestions

Return search term suggestions based on partial queries.

get_article_structure

Extract article structure, headings, and metadata for a given article.

extract_article_links

Extract internal, external, and media links from an article.

get_entry_summary

Get a concise summary of an article with metadata.

get_table_of_contents

Extract a hierarchical table of contents for an article.

get_binary_entry

Retrieve binary content like images, PDFs, or videos from a ZIM entry with optional base64 encoding.

get_server_health

Return server health status and basic metrics.

get_server_configuration

Return detailed server configuration and diagnostics.

diagnose_server_state

Provide comprehensive diagnostics about server state and environment.

resolve_server_conflicts

Identify and resolve conflicts between multiple MCP server instances.