OpenZIM MCP Server for Offline Knowledge Search

Overview

OpenZIM MCP Server is a lightweight service that exposes offline ZIM archives (Wikipedia, educational collections, etc.) via the Model Context Protocol (MCP). It lets LLMs and other AI agents query and retrieve relevant passages from one or more ZIM files without requiring network access to the original websites. The server indexes ZIM content and returns structured search results suitable for use as retrieval-augmented context for models.

This server is useful for developers building privacy-sensitive or low-bandwidth applications: run it on-premises or on a device, point it to ZIM archives, and let downstream AI models request concise, source-attributed passages. The MCP interface is designed to be simple and model-friendly, with endpoints for searching, retrieving article text, and health/telemetry.

Features

• Serve one or many ZIM archives as searchable knowledge sources
• MCP-compatible API endpoints for model-driven retrieval
• Full-text and title search with relevance-ranked results
• Source attribution (ZIM filename, article title, URL within archive)
• Small footprint and high throughput for offline environments
• Configurable access controls (API key / token support)
• Health and metrics endpoints for integration with orchestration/monitoring

Installation / Configuration

Two common deployment methods are Docker (recommended) and building from source.

Quick start with Docker:

# Run the server, exposing port 8080 and mounting a directory with ZIM files
docker run -d \
  --name openzim-mcp \
  -p 8080:8080 \
  -v /path/to/zim:/zim:ro \
  -e MCP_API_KEY="replace-with-your-key" \
  ghcr.io/your-org/openzim-mcp:latest

Basic example using docker-compose:

version: "3.8"
services:
  openzim-mcp:
    image: ghcr.io/your-org/openzim-mcp:latest
    ports:
      - "8080:8080"
    environment:
      - MCP_API_KEY=replace-with-your-key
    volumes:
      - ./zim:/zim:ro

Build and run from source (generic steps — see the repo for language-specific requirements):

git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
# follow the project's README for build commands; common steps:
# make build
# or
# go build ./cmd/mcp-server
./mcp-server --config config.yaml

Example configuration (config.yaml):

server:
  host: "0.0.0.0"
  port: 8080
  api_key: "replace-with-your-key"

zim:
  path: "/zim"          # directory with .zim files
  index_path: "/data/index"  # where indexes are stored
  max_results: 10

logging:
  level: "info"

Security notes:

• Set MCP_API_KEY (or config.api_key) when deploying in any multi-tenant or networked environment.
• Run the container with the ZIM directory mounted read-only.

Available Resources

• ZIM archives: download public ZIM files (Wikipedia, Wikibooks, offline educational bundles) from openzim.org or Kiwix mirrors.
• ZIM tooling: libzim-based utilities and indexers can help pre-build search indexes.
• MCP clients: the server speaks a simple HTTP JSON-based interface suitable for direct use from Python, Node.js, or model-running agents.
• Monitoring: health and metrics endpoints (Prometheus compatible) are available for production setups.

API endpoints (typical):

Example request/response shapes:

• POST /mcp/search
  • body: { “query”: “photosynthesis”, “limit”: 5 }
  • response: list of { title, snippet, zim_file, internal_url, score }

Use Cases

1. Offline tutoring chatbot

   • Ship ZIM bundles containing educational content to low-connectivity schools.
   • Run the MCP server on a local device and let a model generate answers using retrieved passages.
   • Example: student asks “What is mitosis?” → model calls /mcp/search(“mitosis”, 5) → uses returned snippets with citations in the final answer.

2. Secure on-prem knowledge retrieval

   • Sensitive organizations can host ZIM archives of internal documentation in a closed network.
   • LLMs use the MCP server as a retrieval layer without requiring external web access.
   • Example: integration with an internal agent: agent requests context via MCP, then composes a response locally.

3. Research and reproducibility

   • Researchers extract exact passages and provenance from an immutable ZIM snapshot for experiments.
   • Use the server to reproduce retrieval-augmentation experiments against a defined archive.

4. Embedded/offline devices

   • Run on single-board computers or kiosks where internet access is limited.
   • Offer search-driven experiences (museum kiosks, field education systems) backed by ZIM content.

Example calls

Search with curl:

curl -X POST "http://localhost:8080/mcp/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer replace-with-your-key" \
  -d '{"query":"Photosynthesis", "limit":3}'

Python example:

import requests

url