Skip to main content
Glama
AHX47

ZimAgent

by AHX47
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

🤖 ZimAgent Desktop

Offline CRUD + Semantic Search for Wikipedia ZIM Archives

A production-grade PyQt5 desktop application that lets you read, write, edit, and semantically search any Kiwix .zim archive — with local LLM question answering, animated pipeline visualisation, and a built-in MCP server for Claude Desktop / LangChain integration.

Fully offline. No internet connection required after initial model download.

📸 Screenshot

Related MCP server: kiwix-mcp

🚀 Quick Start

1. Clone & Install

git clone https://github.com/yourname/zim-agent-gui
cd zim-agent-gui

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate       # Linux/macOS
.venv\Scripts\activate.bat      # Windows

# Install dependencies
pip install -r requirements.txt

2. Download a ZIM file

# Small Wikipedia excerpt for testing (~90 MB)
wget https://download.kiwix.org/zim/wikipedia/wikipedia_en_wp1_2023-11.zim \
     -O data/test.zim

3. Download GGUF Models (for RAG + LLM)

Place models in the models/ folder:

File

Purpose

Source

embeddinggemma-300m-q4_k_m.gguf

Sentence embeddings

HuggingFace

qwen-0.5b-q4_k_m.gguf

Answer generation

HuggingFace

# Install TurboRag
pip install turborag-ahx47

4. Launch

python run_app.py
# or
python -m zimagent

📦 File Structure

zim-agent-gui/
├── zimagent/                    # Main Python package
│   ├── __init__.py
│   ├── __main__.py              # python -m zimagent
│   ├── main.py                  # App entry-point (QApplication)
│   ├── main_window.py           # Full PyQt5 UI (~600 lines)
│   ├── zim_reader.py            # ZIM article reading (libzim)
│   ├── zim_manager.py           # CRUD + SQLite overlay
│   ├── mcp_server.py            # FastMCP tool server
│   ├── indexer.py               # ZIM → TurboRag indexer
│   ├── agent.py                 # High-level ZimAgent orchestrator
│   ├── semantic_search.py       # TurboRag adapter
│   ├── worker_threads.py        # QThread workers (index, MCP, stats)
│   └── resources/
│       └── style.qss            # Dark cyberpunk QSS theme
│
├── models/                      # GGUF models (user-provided)
│   ├── embeddinggemma-300m-q4_k_m.gguf
│   └── qwen-0.5b-q4_k_m.gguf
│
├── data/                        # ZIM files + index
│
├── scripts/
│   ├── build_exe.bat            # Windows .exe via PyInstaller
│   ├── build_deb.sh             # Linux .deb package
│   └── DEBIAN/control
│
├── run_app.py                   # Standalone launcher
├── requirements.txt
├── setup.py
└── README.md

🧩 Features

Dashboard

  • ZIM Archive Input & CRUD — open any .zim, see file size + article count

  • Pipeline Visualization — animated dashed-arrow diagram: ZIM Reader → Chunking → Gemma Embedding → TurboVec Index + SQLite FTS5

  • Query & Results — ask a question, see semantic results + LLM answer

  • MCP Server mini-panel — one-click toggle with live status

CRUD Operations

  • Full article tree (namespaces A/, B/, …)

  • HTML viewer (QWebEngineView or plain text fallback)

  • Write new articles, edit existing, soft-delete with restore

  • Every change stored in SQLite overlay (base ZIM untouched)

  • Full action log

Semantic Search

  • Semantic search powered by TurboRag vector index

  • Relevance bar for each result

  • LLM-generated answer with source attribution

  • Runs in background thread (UI never blocks)

MCP Server

  • Exposes 8 MCP tools to Claude Desktop / any MCP client

  • SSE or stdio transport

  • Configurable host + port

  • Live server log

⚙️ Configuration

Open ⚙ Settings in the sidebar to configure:

  • Embedding model path

  • LLM model path

  • Vector index path

These are saved for the current session (persistent config coming in v1.1).

📦 Building Installers

Windows .exe

pip install pyinstaller
scripts\build_exe.bat
# Output: dist\ZimAgent.exe

Linux .deb

sudo apt install fakeroot dpkg-dev
bash scripts/build_deb.sh
# Output: zimagent_1.0.0_amd64.deb
sudo dpkg -i zimagent_1.0.0_amd64.deb

🔌 MCP Integration (Claude Desktop)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zimagent": {
      "command": "python",
      "args": ["-m", "zim_agent.mcp_server",
               "--zim", "/path/to/wikipedia.zim",
               "--transport", "stdio"]
    }
  }
}

Or start SSE server from the MCP Server tab and connect via: http://127.0.0.1:8002/sse

📋 MCP Tools Reference

Tool

Parameters

Description

zim_read_article

path

Read article by URL path

zim_search

query, max_results

Full-text + prefix search

zim_write_article

path, title, html

Create or replace article

zim_edit_article

path, new_html, [new_title]

Edit article content

zim_delete_article

path

Soft-delete article

zim_restore_article

path

Restore deleted article

zim_list_modified

—

List all overlay changes

zim_stats

—

Archive + index statistics

🧱 Dependencies

Package

Purpose

PyQt5

GUI framework

PyQtWebEngine

HTML article rendering

libzim

ZIM file reading

turborag-ahx47

Semantic search + RAG

fastmcp

MCP server

psutil

CPU/RAM monitoring

📄 License

MIT — see LICENSE.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/AHX47/Zim-Agent-Gui'

If you have feedback or need assistance with the MCP directory API, please join our Discord server