kiwix-mcp

MCP server and Python client library for Kiwix HTTP servers.

Compatibility

Tested against kiwix-tools (Debian bookworm package) and newer libkiwix-based deployments. Any standard kiwix-serve deployment should work.

Known quirks handled transparently:

• kiwix-serve emits unescaped & in OPDS catalog href attributes

• Newer servers require a book scope when the library spans multiple languages — the client returns a clear error with instructions in that case

• Newer servers use a path-prefixed URL scheme (e.g. /kiwix/content/book_slug) — slug and article URL handling adapts automatically

Tools

Installation

pip install kiwix-mcp

Or with uv:

uv pip install kiwix-mcp

Usage

stdio (Claude Desktop / Claude Code)

kiwix-mcp --base-url http://localhost:8080
# or
KIWIX_BASE_URL=http://localhost:8080 kiwix-mcp

Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "kiwix": {
      "command": "kiwix-mcp",
      "args": ["--base-url", "http://localhost:8080"]
    }
  }
}

Claude Code — add at user scope so it's available in all projects:

claude mcp add --scope user --transport http kiwix https://your-kiwix-mcp-host/mcp/

SSE

kiwix-mcp --transport sse --base-url http://localhost:8080

Then point your MCP client at http://localhost:8000/sse.

HTTP (streamable)

kiwix-mcp --transport streamable-http --base-url http://localhost:8080

Then point your MCP client at http://localhost:8000/mcp.

CORS (browser-based clients)

When using HTTP transports with browser-based MCP clients (e.g. llama-server WebUI), CORS headers are added automatically. By default all origins are allowed.

To restrict allowed origins:

kiwix-mcp --transport streamable-http --base-url http://localhost:8080 \
  --cors-allow-origins "http://localhost:3000,http://myapp.example.com"
# or
CORS_ALLOW_ORIGINS="http://localhost:3000" kiwix-mcp --transport streamable-http --base-url http://localhost:8080

CORS has no effect on stdio transport.

Docker

docker run -e KIWIX_BASE_URL=http://your-kiwix-server:8080 \
  -p 8000:8000 \
  oscillatelabs/kiwix-mcp

Defaults to streamable-http transport bound on 0.0.0.0:8000. Override with env vars:

docker run \
  -e KIWIX_BASE_URL=http://your-kiwix-server:8080 \
  -e TRANSPORT=sse \
  -e HOST=0.0.0.0 \
  -e PORT=8000 \
  -e CORS_ALLOW_ORIGINS="http://localhost:3000" \
  -p 8000:8000 \
  oscillatelabs/kiwix-mcp

Options

Client library

from kiwix_client import KiwixClient, strip_html

c = KiwixClient("http://localhost:8080")

# List all books
books = c.list_books()

# Filter by title keyword
books = c.list_books(q="wikipedia")

# Search
sr = c.search("query")

# Search within a specific book
sr = c.search("query", books="devdocs_en_rust_2025-10")

# Fetch article as plain text
html = c.fetch_article(sr.results[0].url)
plain = strip_html(html)

How the Kiwix API works

kiwix-serve exposes three HTTP surfaces used by this client:

• OPDS catalog (/catalog/v2/entries) — Atom XML with book metadata and slugs; supports ?q=, ?count=, ?start= params

• Full-text search (/search?pattern=…&books.name=…&start=…) — HTML; 25 results/page; books.name= scopes to a specific ZIM slug

• Articles (/{book_slug}/A/{path}) — HTML; use strip_html for plain text

There is no JSON API. Full-text search requires ZIMs built with _ftindex:yes — not all ZIMs include it. Servers with books spanning multiple languages require a book scope for any search request.

Testing

# Install with dev dependencies
pip install -e ".[dev]"

# Run the test suite (no network required)
pytest