AI导哈

Kiwix MCP服务器与客户端库

为Kiwix HTTP服务器提供的MCP服务器和Python客户端库，支持书籍列表、全文搜索和文章获取功能。

  • by OscillateLabsLLC
  • Python
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 OscillateLabsLLC/kiwix-mcp

使用说明

猕猴桃mcp

MCP服务器和Python客户端库 Kiwix HTTP服务器。

兼容性

经过测试 奇异工具 （Debian bookworm 软件包）和更新版本 libkiwix-基于部署。标准 kiwix-serve 部署应该奏效。

透明地处理已知的怪癖：

  • 奇异果发球无伴奏 & 在OPDS目录中 href 属性
  • 当库跨越多种语言时，较新的服务器需要一个图书范围——在这种情况下，客户端会返回一个带有指令的明确错误
  • 较新的服务器使用路径前缀URL方案（例如。 /kiwix/content/book_slug)--slug和文章URL处理自动适应

工具

工具 说明
kiwix_list_books 列出可用的ZIM书籍；可选标题过滤器
kiwix_search 在所有书籍或特定书籍中进行全文搜索
kiwix_fetch_article 通过URL以纯文本形式获取文章

安装

pip install kiwix-mcp

或与 紫外线:

uv pip install kiwix-mcp

用法

stdio（克劳德桌面/克劳德代码）

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

Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json):

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

Claude Code——在用户范围内添加，以便在所有项目中都可用：

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

上海证券交易所

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

然后将您的MCP客户端指向 http://localhost:8000/sse.

HTTP（可流式传输）

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

然后将您的MCP客户端指向 http://localhost:8000/mcp.

CORS（基于浏览器的客户端）

当使用基于浏览器的MCP客户端（例如llama服务器WebUI）的HTTP传输时，CORS标头会自动添加。默认情况下，允许所有来源。

要限制允许的来源：

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对stdio传输没有影响。

码头工人

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

默认为 streamable-http 运输途中 0.0.0.0:8000.用env变量覆盖：

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

选项

标志 默认值 环境
--base-url — KIWIX_BASE_URL
--transport stdio TRANSPORT
--host 127.0.0.1 HOST
--port 8000 PORT
--cors-allow-origins * CORS_ALLOW_ORIGINS

客户端库

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)

Kiwix API的工作原理

kiwix-serve 公开此客户端使用的三个HTTP表面：

  • OPDS目录 (/catalog/v2/entries)--带有图书元数据和slug的Atom XML；支持 ?q=, ?count=, ?start= 参数
  • 全文搜索 (/search?pattern=…&books.name=…&start=…)--HTML；25条结果/页； books.name= 瞄准特定ZIM弹头
  • 条款 (/{book_slug}/A/{path})--HTML；使用 strip_html 对于纯文本

没有JSON API。全文搜索需要使用以下构建的ZIM _ftindex:yes --并非所有ZIM都包含它。具有跨多种语言书籍的服务器需要一个书籍范围来进行任何搜索请求。

测试

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

# Run the test suite (no network required)
pytest

相关 MCP