zim

The ZIM MCP Server provides local, offline access to content stored in ZIM files by exposing tools that let you list available ZIM files, search their contents, and retrieve specific entries. This enables local AI models to perform question answering and information retrieval against offline knowledge resources without requiring an internet connection. The server exposes three primary tools: list_zim_files, which enumerates ZIM files in configured directories; search_zim_file, which searches for a query within a specified ZIM file; and get_zim_entry, which returns a detailed view of a particular article or page within a ZIM file. To use these tools, start the MCP server via your chosen runner (uv/uvx) and then call the tools with the required arguments. The results are returned in structured JSON, including article snippets, paths, and basic metadata, facilitating integration with your local AI workflows.

Prerequisites:

• Install uv (https://uv.sh) as described for your operating system.
• Clone the repository:
  • git clone https://github.com/ThinkInAI-Hackathon/zim-mcp-server.git
• Install dependencies and prepare environment (as needed by uv-based servers):
  • uv sync
• Prepare ZIM files: download and place ZIM files (e.g., Wikipedia, Wiktionary) into a directory you will reference (e.g., D:\ZIM or /home/user/ZIM).
• Start the server using the preferred method (the MCP config can specify a uv/uvx command). Example (adjust paths to your environment):
  • uvx zim-mcp-server
  • or if using uv directly to run a Python module, ensure the server entry is invoked appropriately and points to your ZIM directory.

Tips and common issues:

• Ensure ZIM files are accessible by the server process and that the path is correctly configured in your environment (ZIM_FILES_DIR).
• If you encounter permission or path issues, verify file permissions and use absolute paths.
• The tools do not require internet access once ZIM files are loaded; ensure offline operation by keeping the ZIM data local.
• When integrating with Claude Desktop or other clients, provide the correct local paths to the server and ZIM directory as shown in the configuration examples.
• If you update ZIM files, restart the MCP server to refresh the index/search data.
• Environment variables can help customize paths and buffering behavior; adjust as needed for your runtime environment.