知识库MCP服务

kb-mcp-server是一个基于txtai的模型上下文协议服务器。它允许你将自己收集的文档、代码、笔记等构建成一个可移植的、离线的知识库，然后通过MCP协议让AI助手访问。简单来说，它能帮你为自己的AI打造一个专属的、私密的“第二大脑”。

项目基本信息

一、项目介绍

kb-mcp-server构建在txtai库之上，这是一个强大的“一站式向量数据库”，它融合了语义搜索、知识图谱构建和语言模型工作流。这个服务器提供了一整套命令行工具和MCP接口，让你可以完成从知识库构建到查询的完整流程。

该项目主要包含两部分：知识库构建器（kb_builder）和MCP服务器。

知识库构建器负责“喂”给AI知识。你可以将一堆文档（如PDF、Markdown、代码文件）作为输入，它会对文档进行智能分段、创建向量嵌入，并可选地构建知识图谱。最终，它可以生成一个可移植的、压缩的知识库文件（.tar.gz）。

MCP服务器则负责“读取”这个知识库。当你的AI需要查询信息时，它会通过这个服务器进行语义搜索。服务器会理解问题的含义，而不仅仅是匹配关键词，从知识库中找到最相关的内容返回给AI。如果启用了知识图谱，它甚至能发现不同概念之间的隐含联系。

二、核心优势

完全本地化，数据永不流出：这是该项目最大的优势。所有文档预处理、向量索引和查询都在你的本地机器上完成。你不需要将数据发送给任何外部API或服务。对于处理商业机密、个人隐私或敏感研究数据来说，这是至关重要的特性。

构建可移植、可分享的知识库：你能将所有知识、经验、文档打包成一个或几个文件。知识库可以像普通文件一样复制、备份，甚至分享给同事。启动服务器时，只需要指定这个文件即可，实现了知识和配置的“代码化”。

语义搜索与知识图谱：它不只是做关键词匹配。当你问“如何解决内存泄漏问题”时，它能够理解你的意图，找到真正描述解决方案的段落，即使那些段落中没有“解决”这个词。此外，知识图谱功能可以揭示文档中概念之间的关系，例如找出哪些技术文档频繁引用了某个核心API。

丰富的配置与优化选项：基于txtai，整个系统高度可配置。你可以选择不同的嵌入模型（如sentence-transformers）、调整分块策略、选择混合搜索权重、配置图神经网络等。通过编写YAML配置文件，你可以针对技术文档、学术论文或代码库进行精细优化，得到最佳检索效果。

三、适用场景

场景一：私有技术文档问答。这是最经典的应用。你可以将公司内部的所有技术文档、API说明、故障排查手册构建成一个知识库。然后让AI助手回答：“如何配置数据库连接池？”或“生产环境部署检查清单有哪些？”AI将基于你的内部文档给出准确答案，而非通用信息。

场景二：个人笔记与知识库助手。如果你使用Obsidian、Logseq或Foam等工具积累了大量个人笔记，可以将整个笔记文件夹构建成知识库。之后，你可以问AI：“我关于‘微服务架构’都记了哪些要点？”或者“我之前研究过的关于Rust生命周期的文章中，最佳实践是什么？”

场景三：代码库分析与文档生成。将一个开源项目或你自己的代码仓库（尤其是包含大量注释和README的）构建成知识库。你可以问AI：“这个项目的身份验证模块是如何组织的？”或者“找出所有处理用户输入的函数。”AI能帮你从代码的“知识”层面进行分析。

场景四：学术文献综述辅助。与arxiv-mcp-server不同，这里你可以将本地下载的论文PDF集合构建成知识库。然后进行语义搜索：“找出讨论‘transformer模型参数量与性能关系’的段落。”这能帮你精准定位到论文中的具体论述，而不是只能读摘要。

场景五：离线环境的知识支持。对于开发环境严格隔离、无法连接外网的场景，你可以先在能联网的环境中构建好知识库（比如下载的文档、论文），然后将知识库文件传输到内网，在内网的MCP服务器中加载。AI在无互联网的情况下，依然可以基于知识库提供高质量的信息。

四、安装教程

安装kb-mcp-server有多种方式，这里推荐使用uv和uvx，这是最干净、快捷的方式。

第一步：安装uv

uv是一个快速的Python包管理器。安装命令如下：

macOS 或 Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

第二步：构建你的第一个知识库

假设你有一个包含文档的文件夹（例如~/my_documents），里面有一些Markdown或文本文件。你可以使用uvx直接运行kb-build命令来构建知识库，无需安装任何东西。

uvx --from kb-mcp-server kb-build --input ~/my_documents --export my_knowledge_base.tar.gz

这个命令会处理~/my_documents下的所有文件，最终在当前目录下生成一个名为my_knowledge_base.tar.gz的知识库压缩包。你也可以用--config参数指定自定义的配置文件。

第三步：配置MCP客户端

以Claude Desktop为例。找到其配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

使用文本编辑器打开该文件，添加以下配置。请将--embeddings后的路径替换为你生成的知识库文件（.tar.gz）或文件夹的绝对路径。

{
  "mcpServers": {
    "kb-server": {
      "command": "uvx",
      "args": [
        "kb-mcp-server",
        "--embeddings", 
        "/完整/路径/到/你的/my_knowledge_base.tar.gz"
      ]
    }
  }
}

如果你希望服务器在后台以HTTP模式运行（而非stdio），可以添加--transport sse参数。

重要说明：Claude Desktop等图形化应用可能无法直接找到uvx命令。如果配置后无法连接，你需要使用虚拟环境中Python的绝对路径来运行。首先创建一个虚拟环境并安装包：

uv venv
source .venv/bin/activate
uv pip install kb-mcp-server

然后，找到你虚拟环境中的kb-mcp-server可执行文件（通常在.venv/bin/kb-mcp-server）。在配置中使用其绝对路径：

{
  "mcpServers": {
    "kb-server": {
      "command": "/你的项目路径/.venv/bin/kb-mcp-server",
      "args": ["--embeddings", "/完整/路径/到/你的/my_knowledge_base.tar.gz"]
    }
  }
}

第四步：重启并验证

保存配置文件，完全退出Claude Desktop并重新启动。现在，你可以问一些只在你的个人文档中出现的问题了。例如：“根据我整理的笔记，我是如何定义‘知行合一’的？”

如果配置成功，AI会从你的知识库中查找并回答。

五、使用示例

配置完成后，你的AI就能访问你的专属知识库了。以下是一些典型用法。

示例一：语义搜索查询

你问：“帮我查一下知识库里，关于‘函数式编程的优势’有哪些论述？”

AI会调用MCP服务器的语义搜索功能，返回最相关的文档片段或段落。

示例二：探索性问答

你问：“根据我收集的Rust资料，所有权系统主要解决了什么问题？”

AI会在你的Rust学习笔记或文档中进行语义搜索，总结出核心要点。

示例三：知识图谱查询（如果构建时启用了图谱）

你问：“我的知识库中，‘缓存’和‘数据库’这两个概念之间有什么联系？”

AI可以从知识图谱中找出连接这两个概念的路径和相关文档。

示例四：代码库理解

如果你构建了一个开源项目的代码库知识库，可以问：“找出项目中所有实现了‘观察者模式’的地方。”

AI会搜索代码注释、README或相关文档，定位到描述的段落。

示例五：组合查询

你问：“在关于‘大语言模型’的文档中，有哪些段落同时提到了‘参数高效微调’和‘LoRA’？”

AI会进行精准的语义检索，返回同时包含这两个概念的片段。

六、常见问题

问题一：构建知识库时，如何处理PDF和Word文档？

解决方案：kb_builder依赖于txtai的文件处理管道。txtai默认支持纯文本、Markdown、HTML和PDF。对于PDF，它依赖于pypdf库。对于Word文档，你需要安装docx2txt等额外依赖。最稳妥的方式是将所有文档统一转换为纯文本（.txt）或Markdown（.md）格式后再进行构建。

问题二：搜索结果的准确性不高，或者返回了不相关的内容。

解决方案：知识库的检索质量强烈依赖于你的文档预处理方式。有几个可以优化的方向：

• 选择更好的嵌入模型：在配置文件中修改embeddings.path，例如使用BAAI/bge-large-en-v1.5或intfloat/e5-large-v2等高性能模型。
• 调整分块策略（chunking）：chunk_size和chunk_overlap参数影响很大。过大会引入噪声，过小会丢失上下文。对于技术文档，通常512-1024的token大小比较合适。
• 启用混合搜索：设置scoring: hybrid并调整hybridalpha权重（如0.75），可以平衡关键词匹配（BM25）和语义匹配。

问题三：知识库文件（.tar.gz）太大，加载缓慢。

解决方案：加载速度主要取决于知识库的大小和你选择的嵌入模型（模型大小会影响首次加载时间）。你可以尝试：

• 使用更小的嵌入模型，如all-MiniLM-L6-v2。
• 如果不需要频繁更新，可以预先将知识库文件夹准备好，而不是每次都加载tar.gz文件（解压后加载）。
• 仅将最核心的文档构建成知识库，避免一股脑把所有资料都包含进去。

问题四：构建知识库时，提示内存不足。

解决方案：处理非常大的文档集（如数十GB）时，向量索引可能占用大量内存。你可以：

• 在配置文件中降低batch大小。
• 使用基于磁盘的向量后端，如faiss配合OnDiskInvertedIndexes，或直接使用sqlite-faiss配置。
• 将大型文档集分批处理，构建多个知识库，再在AI层面进行路由。

问题五：MCP客户端提示找不到uvx或kb-mcp-server命令。

解决方案：这是macOS上图形化应用的常见问题，因为它们不加载你的shell配置文件（如.bashrc或.zshrc）。解决方法如前所述：在虚拟环境中安装包，然后在配置中使用虚拟环境中Python二进制文件的绝对路径，或者kb-mcp-server可执行文件的绝对路径。

七、总结

kb-mcp-server是一个将“知识库”和“AI助手”深度结合的优秀项目。它的核心价值在于私有化和可定制。借助txtai强大的能力，你可以将任何数量的本地文档，转换成一个可供AI查询的、高可用的语义搜索引擎。

这个项目最大的魅力在于，它把一个非常复杂的RAG系统，包装成了一个简单、便携、开箱即用的MCP服务器。你不需要理解向量数据库的原理，不需要部署云服务，只需要运行几条命令，就能拥有一个属于自己的、可以离线运行的私有知识问答系统。

对于所有拥有大量私密文档（公司知识库、个人笔记、专业文献）并且希望AI能基于这些内容提供帮助的用户，kb-mcp-server都是一个极其有价值的工具。它赋予了AI“联系上下文”的能力，但这个“上下文”是你自己构建的世界。

如果你希望你的AI真正“懂”你，懂你的文档，懂你的代码，懂你的笔记，那么kb-mcp-server就是你一直在寻找的钥匙。