<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>OpenZIM MCP - Intelligent Knowledge Access for AI Models</title>
<meta name="description" content="OpenZIM MCP is a modern, secure MCP server that enables AI models to access and search ZIM format knowledge bases offline with intelligent, structured access patterns.">
<meta name="keywords" content="OpenZIM, MCP, Model Context Protocol, AI, LLM, knowledge base, offline, ZIM files, Wikipedia, Python, open source, semantic search">
<meta name="author" content="Cameron Rye">
<!-- SEO Meta Tags -->
<link rel="canonical" href="https://cameronrye.github.io/openzim-mcp/">
<meta name="robots" content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1">
<meta name="googlebot" content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1">
<meta name="bingbot" content="index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1">
<meta name="theme-color" content="#2563eb">
<meta name="color-scheme" content="light dark">
<!-- Open Graph / Facebook -->
<meta property="og:type" content="website">
<meta property="og:site_name" content="OpenZIM MCP">
<meta property="og:url" content="https://cameronrye.github.io/openzim-mcp/">
<meta property="og:title" content="OpenZIM MCP - Intelligent Knowledge Access for AI Models">
<meta property="og:description" content="Transform static ZIM archives into dynamic knowledge engines for Large Language Models with intelligent, structured access patterns.">
<meta property="og:image" content="https://cameronrye.github.io/openzim-mcp/assets/og-image.svg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="OpenZIM MCP - Intelligent Knowledge Access for AI Models">
<meta property="og:locale" content="en_US">
<meta property="article:author" content="Cameron Rye">
<meta property="article:modified_time" content="2025-01-15T00:00:00Z">
<!-- Twitter -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@cameronrye">
<meta name="twitter:creator" content="@cameronrye">
<meta name="twitter:url" content="https://cameronrye.github.io/openzim-mcp/">
<meta name="twitter:title" content="OpenZIM MCP - Intelligent Knowledge Access for AI Models">
<meta name="twitter:description" content="Transform static ZIM archives into dynamic knowledge engines for Large Language Models with intelligent, structured access patterns.">
<meta name="twitter:image" content="https://cameronrye.github.io/openzim-mcp/assets/og-image.svg">
<meta name="twitter:image:alt" content="OpenZIM MCP - Intelligent Knowledge Access for AI Models">
<!-- Favicon -->
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg">
<link rel="icon" type="image/x-icon" href="assets/favicon.ico">
<!-- Humans.txt -->
<link rel="author" type="text/plain" href="humans.txt">
<!-- Fonts -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap" rel="stylesheet">
<!-- Styles -->
<link rel="stylesheet" href="assets/styles.css">
<!-- Structured Data - Software Application -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "OpenZIM MCP",
"alternateName": "OpenZIM MCP Server",
"description": "A modern, secure MCP server that enables AI models to access and search ZIM format knowledge bases offline with intelligent, structured access patterns",
"url": "https://cameronrye.github.io/openzim-mcp/",
"softwareVersion": "0.6.0",
"releaseNotes": "https://github.com/cameronrye/openzim-mcp/blob/main/CHANGELOG.md",
"applicationCategory": "DeveloperApplication",
"applicationSubCategory": "AI Tools",
"operatingSystem": "Linux, macOS, Windows",
"programmingLanguage": {
"@type": "ComputerLanguage",
"name": "Python",
"version": "3.12+"
},
"license": "https://opensource.org/licenses/MIT",
"downloadUrl": "https://pypi.org/project/openzim-mcp/",
"installUrl": "https://pypi.org/project/openzim-mcp/",
"codeRepository": "https://github.com/cameronrye/openzim-mcp",
"softwareHelp": "https://github.com/cameronrye/openzim-mcp#readme",
"author": {
"@type": "Person",
"name": "Cameron Rye",
"url": "https://rye.dev"
},
"creator": {
"@type": "Person",
"name": "Cameron Rye",
"url": "https://rye.dev"
},
"maintainer": {
"@type": "Person",
"name": "Cameron Rye",
"url": "https://rye.dev"
},
"offers": {
"@type": "Offer",
"price": "0",
"priceCurrency": "USD",
"availability": "https://schema.org/InStock"
},
"featureList": [
"Dual Mode Support: Simple mode (1 intelligent natural language tool) or Advanced mode (15 specialized tools)",
"Security First: Comprehensive input validation and path traversal protection",
"Smart Retrieval System: Intelligent content extraction with configurable strategies",
"Multi-Instance Management: Handle multiple ZIM files simultaneously",
"Performance Optimized: Intelligent caching and pagination",
"Full-Text Search: Fast search across ZIM archives",
"Metadata Access: Rich metadata and article information",
"Link Extraction: Internal and external link discovery"
],
"keywords": "OpenZIM, MCP, Model Context Protocol, AI, LLM, knowledge base, offline, ZIM files, Wikipedia, Python, semantic search",
"screenshot": "https://cameronrye.github.io/openzim-mcp/assets/og-image.svg",
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "5.0",
"ratingCount": "1",
"bestRating": "5",
"worstRating": "1"
}
}
</script>
<!-- Structured Data - Organization -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "OpenZIM MCP",
"url": "https://cameronrye.github.io/openzim-mcp/",
"logo": "https://cameronrye.github.io/openzim-mcp/assets/favicon.svg",
"sameAs": [
"https://github.com/cameronrye/openzim-mcp",
"https://pypi.org/project/openzim-mcp/"
],
"founder": {
"@type": "Person",
"name": "Cameron Rye",
"url": "https://rye.dev"
},
"contactPoint": {
"@type": "ContactPoint",
"contactType": "Technical Support",
"url": "https://github.com/cameronrye/openzim-mcp/issues"
}
}
</script>
<!-- Structured Data - WebSite -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "WebSite",
"name": "OpenZIM MCP",
"url": "https://cameronrye.github.io/openzim-mcp/",
"description": "Transform static ZIM archives into dynamic knowledge engines for Large Language Models",
"publisher": {
"@type": "Organization",
"name": "OpenZIM MCP",
"logo": {
"@type": "ImageObject",
"url": "https://cameronrye.github.io/openzim-mcp/assets/favicon.svg"
}
},
"inLanguage": "en-US"
}
</script>
<!-- Structured Data - BreadcrumbList -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://cameronrye.github.io/openzim-mcp/"
},
{
"@type": "ListItem",
"position": 2,
"name": "Features",
"item": "https://cameronrye.github.io/openzim-mcp/#features"
},
{
"@type": "ListItem",
"position": 3,
"name": "Installation",
"item": "https://cameronrye.github.io/openzim-mcp/#installation"
},
{
"@type": "ListItem",
"position": 4,
"name": "Documentation",
"item": "https://cameronrye.github.io/openzim-mcp/#documentation"
}
]
}
</script>
<!-- Structured Data - TechArticle for Documentation -->
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "OpenZIM MCP - Intelligent Knowledge Access for AI Models",
"description": "Comprehensive guide to OpenZIM MCP, a modern MCP server for AI models to access ZIM format knowledge bases offline",
"author": {
"@type": "Person",
"name": "Cameron Rye",
"url": "https://rye.dev"
},
"datePublished": "2024-01-01T00:00:00Z",
"dateModified": "2025-01-15T00:00:00Z",
"publisher": {
"@type": "Organization",
"name": "OpenZIM MCP",
"logo": {
"@type": "ImageObject",
"url": "https://cameronrye.github.io/openzim-mcp/assets/favicon.svg"
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://cameronrye.github.io/openzim-mcp/"
},
"articleSection": "Technology",
"keywords": "OpenZIM, MCP, Model Context Protocol, AI, LLM, knowledge base, offline, ZIM files, Wikipedia, Python",
"inLanguage": "en-US"
}
</script>
</head>
<body>
<!-- Skip to main content for accessibility -->
<a href="#main-content" class="skip-link">Skip to main content</a>
<!-- Navigation -->
<nav class="navbar" id="navbar">
<div class="nav-container">
<div class="nav-logo">
<svg class="logo-icon" width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M12 2a3 3 0 0 0-3 3 4 4 0 0 0-4 4v6a4 4 0 0 0 4 4 3 3 0 0 0 3 3 3 3 0 0 0 3-3 4 4 0 0 0 4-4V9a4 4 0 0 0-4-4 3 3 0 0 0-3-3z"/>
<path d="M12 2v20"/>
<path d="M8 7s0-2 4-2 4 2 4 2"/>
<path d="M8 17s0 2 4 2 4-2 4-2"/>
</svg>
<span class="logo-text">OpenZIM MCP</span>
</div>
<div class="nav-menu" id="nav-menu">
<a href="#home" class="nav-link">Home</a>
<a href="#features" class="nav-link">Features</a>
<a href="#smart-retrieval" class="nav-link">Smart Retrieval</a>
<a href="#security" class="nav-link">Security</a>
<a href="#installation" class="nav-link">Installation</a>
<a href="#usage" class="nav-link">Usage</a>
<a href="#documentation" class="nav-link">Documentation</a>
<a href="https://github.com/cameronrye/openzim-mcp" class="nav-link nav-link-github" target="_blank">
<span class="github-icon">⭐</span> GitHub
</a>
<button class="theme-toggle" id="theme-toggle" aria-label="Toggle dark mode">
<span class="theme-icon" id="theme-icon">🌙</span>
</button>
</div>
<div class="nav-toggle" id="nav-toggle">
<span class="bar"></span>
<span class="bar"></span>
<span class="bar"></span>
</div>
</div>
</nav>
<!-- Hero Section -->
<main id="main-content">
<section id="home" class="hero">
<div class="container">
<div class="hero-content">
<div class="hero-badge">
<span class="badge-icon">⚡</span>
<span>Built for LLM Intelligence</span>
</div>
<h1 class="hero-title">
Transform Static ZIM Archives into
<span class="gradient-text">Dynamic Knowledge Engines</span>
</h1>
<p class="hero-description">
OpenZIM MCP is a modern, secure MCP server that enables AI models to access and search
ZIM format knowledge bases offline with intelligent, structured access patterns.
Choose between Simple mode (default) or Advanced mode to match your needs.
</p>
<div class="hero-buttons">
<a href="#installation" class="btn btn-primary">
<span class="btn-icon">→</span>
Get Started
</a>
<a href="https://github.com/cameronrye/openzim-mcp" class="btn btn-secondary" target="_blank">
<span class="btn-icon">↗</span>
View on GitHub
</a>
</div>
<div class="hero-stats">
<div class="stat">
<div class="stat-number" id="version-display">v0.5.1</div>
<div class="stat-label">Latest Release</div>
</div>
<div class="stat">
<div class="stat-number">90%+</div>
<div class="stat-label">Test Coverage</div>
</div>
<div class="stat">
<div class="stat-number">0</div>
<div class="stat-label">Known Vulnerabilities</div>
</div>
<div class="stat">
<div class="stat-number">2 Modes</div>
<div class="stat-label">Simple & Advanced</div>
</div>
</div>
</div>
<div class="hero-visual">
<div class="code-window">
<div class="code-header">
<div class="code-dots">
<span class="dot red"></span>
<span class="dot yellow"></span>
<span class="dot green"></span>
</div>
<div class="code-title">MCP Configuration</div>
</div>
<div class="code-content">
<pre><code>{
"openzim-mcp": {
"command": "uv",
"args": [
"run", "openzim-mcp",
"/path/to/zim/files"
]
}
}</code></pre>
</div>
</div>
</div>
</div>
</section>
<!-- Features Section -->
<section id="features" class="features">
<div class="container">
<div class="section-header">
<h2 class="section-title">Why LLMs Love OpenZIM MCP</h2>
<p class="section-description">
Unlike basic file readers, OpenZIM MCP provides intelligent, structured access
that LLMs need to effectively navigate and understand vast knowledge repositories.
</p>
</div>
<div class="features-grid">
<div class="feature-card">
<div class="feature-icon">🎯</div>
<h3 class="feature-title">Dual Mode Support</h3>
<p class="feature-description">
Choose Simple mode (1 intelligent natural language tool, default) or Advanced mode
(15 specialized tools) to match your LLM's capabilities.
</p>
</div>
<div class="feature-card">
<div class="feature-icon">🧭</div>
<h3 class="feature-title">Smart Navigation</h3>
<p class="feature-description">
Browse by namespace (articles, metadata, media) instead of blind searching.
Get structured access to content organization.
</p>
</div>
<div class="feature-card">
<div class="feature-icon">🔍</div>
<h3 class="feature-title">Context-Aware Discovery</h3>
<p class="feature-description">
Get article structure, relationships, and metadata for deeper understanding.
Extract links and content connections.
</p>
</div>
<div class="feature-card">
<div class="feature-icon">🎯</div>
<h3 class="feature-title">Intelligent Search</h3>
<p class="feature-description">
Advanced filtering, auto-complete suggestions, and relevance-ranked results
with namespace and content type filters.
</p>
</div>
<div class="feature-card">
<div class="feature-icon">⚡</div>
<h3 class="feature-title">High Performance</h3>
<p class="feature-description">
LRU cache with TTL, intelligent eviction policies, and optimized ZIM operations.
90%+ test coverage ensures reliability at scale.
</p>
</div>
<div class="feature-card">
<div class="feature-icon">🔗</div>
<h3 class="feature-title">Relationship Mapping</h3>
<p class="feature-description">
Extract internal/external links to understand content connections.
Build knowledge graphs from ZIM content.
</p>
</div>
<div class="feature-card">
<div class="feature-icon">🔒</div>
<h3 class="feature-title">Security First</h3>
<p class="feature-description">
Comprehensive input validation, path traversal protection, and secure
resource management with type safety.
</p>
</div>
</div>
</div>
</section>
<!-- Smart Retrieval System Section -->
<section id="smart-retrieval" class="smart-retrieval">
<div class="container">
<div class="section-header">
<h2 class="section-title">🧠 Smart Retrieval System</h2>
<p class="section-description">
Advanced intelligent entry retrieval with automatic fallback and path mapping for reliable access to ZIM content.
</p>
</div>
<div class="smart-retrieval-content">
<div class="retrieval-features">
<div class="retrieval-feature">
<div class="retrieval-icon">🎯</div>
<h3 class="retrieval-title">Direct Access First</h3>
<p class="retrieval-description">
Attempts to retrieve entries using the exact path provided, optimizing for speed and accuracy.
</p>
</div>
<div class="retrieval-feature">
<div class="retrieval-icon">🔄</div>
<h3 class="retrieval-title">Automatic Fallback</h3>
<p class="retrieval-description">
When direct access fails, automatically searches using various search terms and path variations.
</p>
</div>
<div class="retrieval-feature">
<div class="retrieval-icon">💾</div>
<h3 class="retrieval-title">Path Mapping Cache</h3>
<p class="retrieval-description">
Caches successful path mappings to improve performance for repeated access patterns.
</p>
</div>
<div class="retrieval-feature">
<div class="retrieval-icon">🛠️</div>
<h3 class="retrieval-title">Enhanced Error Guidance</h3>
<p class="retrieval-description">
Provides clear, actionable guidance when entries cannot be found, designed for LLM users.
</p>
</div>
</div>
<div class="retrieval-example">
<h3 class="example-title">How It Works</h3>
<div class="code-block">
<pre><code># The system automatically handles path encoding differences:
# ✅ Direct access: "A/Machine_Learning"
# ✅ Fallback search: "Machine Learning", "machine learning"
# ✅ Cached mapping: Future requests use cached path
# No more manual search-first methodology needed!
get_zim_entry(zim_file, "A/Machine_Learning")</code></pre>
</div>
</div>
</div>
</div>
</section>
<!-- Security Features Section -->
<section id="security" class="security">
<div class="container">
<div class="section-header">
<h2 class="section-title">🔒 Enterprise-Grade Security</h2>
<p class="section-description">
Comprehensive security measures designed to protect against vulnerabilities and ensure safe operation in production environments.
</p>
</div>
<div class="security-grid">
<div class="security-feature">
<div class="security-icon">🛡️</div>
<h3 class="security-title">Path Traversal Protection</h3>
<p class="security-description">
Advanced path validation prevents directory traversal attacks using secure path checking with Python 3.9+ features.
</p>
<div class="security-details">
<span class="security-tag">CRITICAL</span>
<span class="security-status">✅ Fixed in v0.2.0</span>
</div>
</div>
<div class="security-feature">
<div class="security-icon">🔍</div>
<h3 class="security-title">Input Validation & Sanitization</h3>
<p class="security-description">
Comprehensive input validation with length limits, character filtering, and sanitization to prevent injection attacks.
</p>
<div class="security-details">
<span class="security-tag">HIGH</span>
<span class="security-status">✅ Implemented</span>
</div>
</div>
<div class="security-feature">
<div class="security-icon">🔐</div>
<h3 class="security-title">Type Safety & Validation</h3>
<p class="security-description">
Full type annotations with Pydantic validation ensure data integrity and prevent type-related vulnerabilities.
</p>
<div class="security-details">
<span class="security-tag">MEDIUM</span>
<span class="security-status">✅ Complete</span>
</div>
</div>
<div class="security-feature">
<div class="security-icon">📊</div>
<h3 class="security-title">Secure Error Handling</h3>
<p class="security-description">
Sanitized error messages prevent information disclosure while providing helpful guidance for legitimate users.
</p>
<div class="security-details">
<span class="security-tag">MEDIUM</span>
<span class="security-status">✅ Enhanced</span>
</div>
</div>
</div>
<div class="security-stats">
<div class="security-stat">
<div class="stat-number">0</div>
<div class="stat-label">Known Vulnerabilities</div>
</div>
<div class="security-stat">
<div class="stat-number">90%+</div>
<div class="stat-label">Test Coverage</div>
</div>
<div class="security-stat">
<div class="stat-number">100%</div>
<div class="stat-label">Type Annotated</div>
</div>
</div>
</div>
</section>
<!-- Advanced Features Section -->
<section id="advanced-features" class="advanced-features">
<div class="container">
<div class="section-header">
<h2 class="section-title">⚡ Advanced Enterprise Features</h2>
<p class="section-description">
Production-ready capabilities for enterprise deployments, monitoring, and multi-instance environments.
</p>
</div>
<div class="advanced-grid">
<div class="advanced-feature">
<div class="advanced-icon">🔄</div>
<h3 class="advanced-title">Multi-Instance Management</h3>
<p class="advanced-description">
Automatic instance tracking and conflict detection ensures reliable operation when multiple server instances are running.
</p>
<ul class="advanced-list">
<li>Automatic instance registration with unique process IDs</li>
<li>Configuration hash validation for compatibility</li>
<li>Stale instance cleanup and orphaned file detection</li>
<li>Real-time conflict detection and resolution</li>
</ul>
</div>
<div class="advanced-feature">
<div class="advanced-icon">📊</div>
<h3 class="advanced-title">Health Monitoring & Diagnostics</h3>
<p class="advanced-description">
Comprehensive health checks and diagnostic tools provide deep insights into server performance and status.
</p>
<ul class="advanced-list">
<li>Built-in health check endpoints</li>
<li>Cache performance metrics and statistics</li>
<li>Instance tracking status and recommendations</li>
<li>Configuration validation and diagnostics</li>
</ul>
</div>
<div class="advanced-feature">
<div class="advanced-icon">🧠</div>
<h3 class="advanced-title">Intelligent Caching System</h3>
<p class="advanced-description">
Advanced LRU cache with TTL support and intelligent eviction policies optimizes performance for large-scale deployments.
</p>
<ul class="advanced-list">
<li>LRU (Least Recently Used) eviction strategy</li>
<li>Configurable TTL (Time To Live) for entries</li>
<li>Automatic expired entry cleanup</li>
<li>Path mapping cache for retrieval optimization</li>
</ul>
</div>
<div class="advanced-feature">
<div class="advanced-icon">🔧</div>
<h3 class="advanced-title">Modern Architecture</h3>
<p class="advanced-description">
Modular design with dependency injection, full type safety, and comprehensive configuration management.
</p>
<ul class="advanced-list">
<li>Dependency injection for testability</li>
<li>100% type annotations with mypy validation</li>
<li>Pydantic-based configuration with validation</li>
<li>Structured logging with configurable levels</li>
</ul>
</div>
</div>
</div>
</section>
<!-- Developer Experience Section -->
<section id="developer-experience" class="developer-experience">
<div class="container">
<div class="section-header">
<h2 class="section-title">🛠️ Developer Experience</h2>
<p class="section-description">
Modern development workflow with automated releases, comprehensive tooling, and enterprise-grade CI/CD.
</p>
</div>
<div class="dev-experience-grid">
<div class="dev-feature">
<div class="dev-icon">🚀</div>
<h3 class="dev-title">Automated Release System</h3>
<p class="dev-description">
Release-please integration with semantic versioning, automated changelog generation, and PyPI deployment.
</p>
<div class="dev-tags">
<span class="dev-tag">Release Please</span>
<span class="dev-tag">Semantic Versioning</span>
<span class="dev-tag">Auto PyPI</span>
</div>
</div>
<div class="dev-feature">
<div class="dev-icon">🔧</div>
<h3 class="dev-title">Enhanced Makefile Workflow</h3>
<p class="dev-description">
Comprehensive development workflow with categorized help, security scanning, and cross-platform compatibility.
</p>
<div class="dev-tags">
<span class="dev-tag">Make Targets</span>
<span class="dev-tag">Security Scanning</span>
<span class="dev-tag">Quality Checks</span>
</div>
</div>
<div class="dev-feature">
<div class="dev-icon">🧪</div>
<h3 class="dev-title">Comprehensive Testing</h3>
<p class="dev-description">
90%+ test coverage with pytest, benchmarking, integration tests, and automated quality assurance.
</p>
<div class="dev-tags">
<span class="dev-tag">90%+ Coverage</span>
<span class="dev-tag">Benchmarks</span>
<span class="dev-tag">Integration Tests</span>
</div>
</div>
<div class="dev-feature">
<div class="dev-icon">🔍</div>
<h3 class="dev-title">Code Quality Tools</h3>
<p class="dev-description">
Black formatting, flake8 linting, mypy type checking, bandit security scanning, and pre-commit hooks.
</p>
<div class="dev-tags">
<span class="dev-tag">Black</span>
<span class="dev-tag">MyPy</span>
<span class="dev-tag">Bandit</span>
</div>
</div>
</div>
<div class="dev-workflow">
<h3 class="workflow-title">Development Workflow</h3>
<div class="code-block">
<pre><code># Complete development setup in one command
make install
# Run all quality checks
make check
# Run tests with coverage
make test
# Security scanning
make security
# Build and publish
make build && make publish</code></pre>
</div>
</div>
</div>
</section>
<!-- Installation Section -->
<section id="installation" class="installation">
<div class="container">
<div class="section-header">
<h2 class="section-title">Quick Installation</h2>
<p class="section-description">
Get up and running with OpenZIM MCP in just a few minutes.
</p>
</div>
<div class="installation-steps">
<div class="step">
<div class="step-number">1</div>
<div class="step-content">
<h3 class="step-title">Install with uv</h3>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#install-code">
<span class="copy-icon">📋</span>
</button>
<pre><code id="install-code"># Install OpenZIM MCP with uv (recommended)
uv add openzim-mcp
# Or install globally with uv
uv tool install openzim-mcp</code></pre>
</div>
</div>
</div>
<div class="step">
<div class="step-number">2</div>
<div class="step-content">
<h3 class="step-title">Prepare ZIM Files</h3>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#zim-code">
<span class="copy-icon">📋</span>
</button>
<pre><code id="zim-code"># Create directory for ZIM files
mkdir ~/zim-files
# Download ZIM files from Kiwix Library
# https://browse.library.kiwix.org/</code></pre>
</div>
</div>
</div>
<div class="step">
<div class="step-number">3</div>
<div class="step-content">
<h3 class="step-title">Run the Server</h3>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#run-code">
<span class="copy-icon">📋</span>
</button>
<pre><code id="run-code"># Start the MCP server
uv run openzim-mcp /path/to/zim/files
# Or if installed globally
openzim-mcp /path/to/zim/files</code></pre>
</div>
</div>
</div>
</div>
<!-- Development Installation -->
<div class="dev-install">
<h3 class="dev-install-title">Development Installation</h3>
<p class="dev-install-description">
For contributors and developers who want to work with the source code or need the latest features:
</p>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#dev-install-code">
<span class="copy-icon">📋</span>
</button>
<pre><code id="dev-install-code"># Clone the repository
git clone https://github.com/cameronrye/openzim-mcp.git
cd openzim-mcp
# Install dependencies
uv sync
# Run from source
uv run python -m openzim_mcp /path/to/zim/files</code></pre>
</div>
</div>
</div>
</div>
</section>
<!-- Usage Examples Section -->
<section id="usage" class="usage">
<div class="container">
<div class="section-header">
<h2 class="section-title">Usage Examples</h2>
<p class="section-description">
See OpenZIM MCP in action with real-world examples and API calls.
</p>
</div>
<div class="usage-tabs">
<div class="tab-buttons">
<button class="tab-btn active" data-tab="search">Search Content</button>
<button class="tab-btn" data-tab="browse">Browse Namespaces</button>
<button class="tab-btn" data-tab="structure">Article Structure</button>
<button class="tab-btn" data-tab="config">MCP Config</button>
</div>
<div class="tab-content">
<div class="tab-pane active" id="search">
<div class="example-block">
<h4>Search ZIM Files</h4>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#search-example">
<span class="copy-icon">📋</span>
</button>
<pre><code id="search-example">{
"name": "search_zim_file",
"arguments": {
"zim_file_path": "wikipedia_en_100_2025-08.zim",
"query": "artificial intelligence",
"limit": 5
}
}</code></pre>
</div>
<div class="example-result">
<h5>Response:</h5>
<pre><code>Found 42 matches for "artificial intelligence", showing 1-5:
## 1. Artificial Intelligence
Path: Artificial_intelligence
Snippet: Artificial intelligence (AI) is intelligence demonstrated by machines...
## 2. Machine Learning
Path: Machine_learning
Snippet: Machine learning is a subset of artificial intelligence...</code></pre>
</div>
</div>
</div>
<div class="tab-pane" id="browse">
<div class="example-block">
<h4>Browse Namespaces</h4>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#browse-example">
<span class="copy-icon">📋</span>
</button>
<pre><code id="browse-example">{
"name": "browse_namespace",
"arguments": {
"zim_file_path": "wikipedia_en_100_2025-08.zim",
"namespace": "C",
"limit": 10,
"offset": 0
}
}</code></pre>
</div>
<div class="example-result">
<h5>Response:</h5>
<pre><code>{
"namespace": "C",
"total_in_namespace": 80000,
"offset": 0,
"limit": 10,
"returned_count": 10,
"has_more": true,
"entries": [
{
"path": "C/Biology",
"title": "Biology",
"content_type": "text/html",
"preview": "Biology is the scientific study of life..."
}
]
}</code></pre>
</div>
</div>
</div>
<div class="tab-pane" id="structure">
<div class="example-block">
<h4>Get Article Structure</h4>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#structure-example">
<span class="copy-icon">📋</span>
</button>
<pre><code id="structure-example">{
"name": "get_article_structure",
"arguments": {
"zim_file_path": "wikipedia_en_100_2025-08.zim",
"entry_path": "C/Evolution"
}
}</code></pre>
</div>
<div class="example-result">
<h5>Response:</h5>
<pre><code>{
"title": "Evolution",
"path": "C/Evolution",
"content_type": "text/html",
"headings": [
{"level": 1, "text": "Evolution", "id": "evolution"},
{"level": 2, "text": "History", "id": "history"},
{"level": 2, "text": "Mechanisms", "id": "mechanisms"}
],
"sections": [
{
"title": "Evolution",
"level": 1,
"content_preview": "Evolution is the change in heritable traits...",
"word_count": 150
}
],
"word_count": 5000
}</code></pre>
</div>
</div>
</div>
<div class="tab-pane" id="config">
<div class="example-block">
<h4>MCP Client Configuration - Simple Mode (Default)</h4>
<div class="code-block">
<button class="copy-btn" data-clipboard-target="#config-example">
<span class="copy-icon">📋</span>
</button>
<pre><code id="config-example">{
"mcpServers": {
"openzim-mcp": {
"command": "uv",
"args": [
"run",
"openzim-mcp",
"/path/to/zim/files"
]
}
}
}</code></pre>
</div>
<div class="example-result">
<h5>Advanced Mode (15 specialized tools):</h5>
<pre><code>{
"mcpServers": {
"openzim-mcp-advanced": {
"command": "openzim-mcp",
"args": [
"--mode", "advanced",
"/path/to/zim/files"
]
}
}
}</code></pre>
<h5>Environment Variables (Optional):</h5>
<pre><code># Tool mode (default: simple)
export OPENZIM_MCP_TOOL_MODE=simple
# Cache configuration
export OPENZIM_MCP_CACHE__ENABLED=true
export OPENZIM_MCP_CACHE__MAX_SIZE=200
export OPENZIM_MCP_CACHE__TTL_SECONDS=7200
# Content configuration
export OPENZIM_MCP_CONTENT__MAX_CONTENT_LENGTH=200000
export OPENZIM_MCP_CONTENT__SNIPPET_LENGTH=2000
# Logging configuration
export OPENZIM_MCP_LOGGING__LEVEL=INFO</code></pre>
</div>
</div>
</div>
</div>
</div>
</div>
</section>
<!-- Documentation Section -->
<section id="documentation" class="documentation">
<div class="container">
<div class="section-header">
<h2 class="section-title">Documentation & Resources</h2>
<p class="section-description">
Comprehensive guides, API references, and community resources to help you get the most out of OpenZIM MCP.
</p>
</div>
<div class="docs-grid">
<div class="doc-card">
<div class="doc-icon">📚</div>
<h3 class="doc-title">API Reference</h3>
<p class="doc-description">
Complete documentation of all available MCP tools, parameters, and response formats.
</p>
<a href="https://github.com/cameronrye/openzim-mcp#-api-reference" class="doc-link" target="_blank">
View API Docs →
</a>
</div>
<div class="doc-card">
<div class="doc-icon">🚀</div>
<h3 class="doc-title">Quick Start Guide</h3>
<p class="doc-description">
Step-by-step tutorial to get OpenZIM MCP running in your environment quickly.
</p>
<a href="https://github.com/cameronrye/openzim-mcp/wiki/Quick-Start-Tutorial" class="doc-link" target="_blank">
Start Tutorial →
</a>
</div>
<div class="doc-card">
<div class="doc-icon">⚙️</div>
<h3 class="doc-title">Configuration Guide</h3>
<p class="doc-description">
Advanced configuration options, environment variables, and performance tuning.
</p>
<a href="https://github.com/cameronrye/openzim-mcp/wiki/Configuration-Guide" class="doc-link" target="_blank">
Configure →
</a>
</div>
<div class="doc-card">
<div class="doc-icon">🔧</div>
<h3 class="doc-title">Troubleshooting</h3>
<p class="doc-description">
Common issues, solutions, and debugging tips for OpenZIM MCP deployment.
</p>
<a href="https://github.com/cameronrye/openzim-mcp/wiki/Troubleshooting-Guide" class="doc-link" target="_blank">
Get Help →
</a>
</div>
<div class="doc-card">
<div class="doc-icon">🏗️</div>
<h3 class="doc-title">Architecture Overview</h3>
<p class="doc-description">
Deep dive into the system architecture, components, and design decisions.
</p>
<a href="https://github.com/cameronrye/openzim-mcp/wiki/Architecture-Overview" class="doc-link" target="_blank">
Learn More →
</a>
</div>
<div class="doc-card">
<div class="doc-icon">🤝</div>
<h3 class="doc-title">Contributing</h3>
<p class="doc-description">
Guidelines for contributing code, reporting issues, and joining the community.
</p>
<a href="https://github.com/cameronrye/openzim-mcp/blob/main/CONTRIBUTING.md" class="doc-link" target="_blank">
Contribute →
</a>
</div>
</div>
</div>
</section>
</main>
<!-- Footer -->
<footer class="footer">
<div class="container">
<div class="footer-content">
<div class="footer-section">
<div class="footer-logo">
<svg class="logo-icon" width="32" height="32" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
<path d="M12 2a3 3 0 0 0-3 3 4 4 0 0 0-4 4v6a4 4 0 0 0 4 4 3 3 0 0 0 3 3 3 3 0 0 0 3-3 4 4 0 0 0 4-4V9a4 4 0 0 0-4-4 3 3 0 0 0-3-3z"/>
<path d="M12 2v20"/>
<path d="M8 7s0-2 4-2 4 2 4 2"/>
<path d="M8 17s0 2 4 2 4-2 4-2"/>
</svg>
<span class="logo-text">OpenZIM MCP</span>
</div>
<p class="footer-description">
Transform static ZIM archives into dynamic knowledge engines for AI models.
</p>
</div>
<div class="footer-section">
<h4 class="footer-title">Resources</h4>
<ul class="footer-links">
<li><a href="https://github.com/cameronrye/openzim-mcp">GitHub Repository</a></li>
<li><a href="https://github.com/cameronrye/openzim-mcp/wiki">Documentation</a></li>
<li><a href="https://github.com/cameronrye/openzim-mcp/issues">Issues</a></li>
<li><a href="https://github.com/cameronrye/openzim-mcp/releases">Releases</a></li>
</ul>
</div>
<div class="footer-section">
<h4 class="footer-title">Community</h4>
<ul class="footer-links">
<li><a href="https://modelcontextprotocol.io/">Model Context Protocol</a></li>
<li><a href="https://openzim.org/">OpenZIM Project</a></li>
<li><a href="https://www.kiwix.org/">Kiwix</a></li>
<li><a href="https://browse.library.kiwix.org/">ZIM Library</a></li>
</ul>
</div>
<div class="footer-section">
<h4 class="footer-title">License</h4>
<p class="footer-license">
Released under the <a href="https://opensource.org/licenses/MIT">MIT License</a>
</p>
<div class="footer-badges">
<img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+">
<img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="MIT License">
</div>
</div>
</div>
<div class="footer-bottom">
<p>Made with <span class="beating-heart">❤️</span> by <a href="https://rye.dev" target="_blank" rel="noopener noreferrer">Cameron Rye</a></p>
</div>
</div>
</footer>
<!-- Scripts -->
<script src="assets/script.js"></script>
</body>
</html>
