Skip to main content
Glama
KnowledgeBase MCP

KnowledgeBase MCP

by admin0330

📚 KnowledgeBase MCP (kb-mcp)

License: MIT Python 3.10+ MCP Standard

A portable, mount-tolerant Model Context Protocol (MCP) server for personal knowledge bases on external storage (macOS APFS / external SSDs).

专为外置固态硬盘/大容量移动存储设计的个人知识库 MCP 智能服务,具备热插拔防崩溃、混合语义与全文检索(FTS5 + BM25 + FastEmbed)、AI 自动化整理与原子大纲自愈能力。


🌟 核心特性

  • 即用即连与拔盘容错 (Mount-Tolerant):

    • 硬盘未连接时,服务优雅返回离线占位状态,绝不导致 Claude Desktop 或 Cursor 启动崩溃。

  • 结构化收敛架构:

    • 外置硬盘根目录下仅保留单一 Database/ 文件夹,整洁清爽,内含待整理收件箱 _Inbox 与分类归档。

  • 混合检索能力:

    • 内置基于 SQLite FTS5 的 Trigram 中文子串分词 + BM25 排名,并可选 FastEmbed 本地向量语义召回。

  • AI 智能整理工作流:

    • 提供 kb_scan_inbox、kb_move_file、kb_rename_file、kb_update_index_md 等工具,支持 AI 全自动内容分析、规范化重命名归档并同步更新 INDEX.md。


Related MCP server: MoonLink

🚀 方式一:直接使用 GitHub 仓库调用(零安装 / 推荐)

如果你使用 Claude Desktop、Cursor 或任何支持 MCP 的客户端,只需在配置文件中直接引用该 GitHub 仓库,即可通过 uvx 自动拉取运行,无需手动克隆代码!

Claude Desktop 配置示例

配置文件路径:~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kb-retrieval": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/admin0330/kb-mcp.git",
        "kb-mcp"
      ],
      "env": {
        "KB_VOLUME": "/Volumes/KnowledgeBase/Database"
      }
    },
    "kb-files": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Volumes/KnowledgeBase/Database"
      ]
    }
  }
}

提示:如果需要启用向量语义检索,只需在 args 中添加 --with 和 fastembed,并设置环境变量 KB_ENABLE_SEMANTIC: "1"。


🛠 方式二:本地克隆与自包含部署

如果你希望将工具链与运行环境完全本地化(或随外置硬盘携带):

# 1. 克隆仓库
git clone https://github.com/admin0330/kb-mcp.git
cd kb-mcp

# 2. 一键配置环境 (自动通过 uv 安装 Python 3.11 独立虚拟环境)
./scripts/setup.sh

# 3. 初始化外置硬盘目录结构 (首次使用)
./scripts/init_drive.sh /Volumes/KnowledgeBase

📂 外置硬盘标准目录规范

/Volumes/KnowledgeBase/
└── Database/                  <-- 根目录唯一总入口
    ├── _Inbox/                <-- 【缓冲区】平时将待整理的文档、电子书、论文直接丢这里
    ├── 01_Documents/          <-- 通用文档、合同、方案、报告
    ├── 02_Books/              <-- 电子书、技术手册 (PDF/EPUB)
    ├── 03_Notes/              <-- 个人笔记、Markdown 卡片
    ├── 04_Archive/            <-- 历史归档文件
    ├── mcp/                   <-- 随盘携带的 MCP 系统与说明
    ├── .mcp_meta/             <-- SQLite 检索库 (index.db) 与日志 (organize.log)
    └── INDEX.md               <-- 全库大纲索引(AI 整理后自动同步)

🧰 提供的 MCP 工具清单

工具名称

功能描述

kb_status

报告硬盘挂载状态、分类目录以及已索引文件统计。

kb_search

全文/关键词/语义检索,返回命中的文档段落、匹配得分与来源路径。

kb_reindex

增量扫描外置硬盘中的新文件并更新索引库(支持 full=True 全量重构)。

kb_scan_inbox

扫描 _Inbox/ 目录下的待整理文件并生成内容预览供 AI 决策。

kb_move_file

将文件从一个目录移动到另一个目录,并支持原子化重命名与索引同步。

kb_rename_file

对指定文件按标准规则重命名并同步索引。

kb_create_directory

在知识库内创建新的分类子目录。

kb_read_document

提取指定文档的全文纯文本(支持 PDF、Word、PPT、EPUB、Markdown 等)。

kb_list_tree

获取指定子目录的树状结构(支持深度限制)。

kb_log

记录整理流水账到外置硬盘日志中。

kb_update_index_md

重新生成并原子化覆盖根目录下的 INDEX.md 索引大纲。

kb_health_check

检查待处理积压、死链、未收录进 INDEX.md 的孤立文件。


💬 常用日常提示词模板

1. 【一键整理收件箱】

“请调用 kb_scan_inbox 检查外置硬盘 _Inbox 里的所有新文件:

  1. 根据内容为每个文件重命名为 YYYY-MM-DD_[主题]_[关键词].[ext];

  2. 移动到对应分类目录(如 01_Documents、02_Books 等);

  3. 调用 kb_update_index_md 更新根目录索引并调用 kb_reindex 增量更新检索库。”

2. 【智能检索与问答】

“请在知识库中检索关于‘[关键词/技术点]’的资料,总结核心结论,并注明引用自哪个文件。”

3. 【知识库体检】

“请运行 kb_health_check 检查知识库健康状态,并汇报积压与未索引情况。”


📄 开源协议

本项目采用 MIT License 开源协议。

Available Tools

12 tools
kb_create_directoryB

Create a directory (and parents) under the volume root.

Inputs: relpath (required). Returns: result

kb_health_checkA

Audit the knowledge base for common problems.

Reports: files still in _Inbox (backlog), files on disk that are not referenced in INDEX.md (orphans), INDEX.md links that point to missing files (dead links), and files not yet in the search index.

Inputs: no named parameters. Returns: result

kb_list_treeC

List the directory tree under subdir (depth-limited).

Inputs: depth, subdir. Returns: result

kb_logB

Append a line to the organize log (.mcp_meta/organize.log).

Inputs: message (required). Returns: result

kb_move_fileB

Move (and optionally rename) a file into a category directory.

The search index is updated in place — no reindex needed afterwards.

:param src_rel: Current path, e.g. _Inbox/report.pdf. :param dest_dir_rel: Target directory, e.g. 01_Documents. :param new_name: Optional new filename; keeps the original when empty.

Inputs: src_rel (required), dest_dir_rel (required), new_name. Returns: result

kb_read_documentA

Return the extracted plain text of one document (for quoting/summarising).

:param relpath: Path relative to the volume root, e.g. _Inbox/foo.pdf. :param max_chars: Maximum characters to return (1-50000).

Inputs: relpath (required), max_chars. Returns: result

kb_reindexA

Scan the volume and update the search index incrementally.

:param full: When true, re-extract every file instead of only changed ones.

Inputs: full. Returns: result

kb_rename_fileA

Rename a file in place (same directory). Index is kept in sync.

Inputs: src_rel (required), new_name (required). Returns: result

kb_scan_inboxA

List files in _Inbox with a short content preview for triage.

Use the previews to decide a target category and a new name, then call :func:kb_move_file.

Inputs: preview_chars. Returns: result

kb_statusA

Report whether the drive is mounted and basic index statistics.

Inputs: no named parameters. Returns: result

kb_update_index_mdA

Regenerate the root INDEX.md from the current directory contents.

Writes atomically (temp file + rename) so an interrupted run never leaves a truncated index.

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools target a clearly distinct operation (search, read, move, rename, status, health check). Minor overlap exists between kb_move_file and kb_rename_file (move also renames), and the three 'index' concepts (kb_reindex, kb_update_index_md, kb_status) could be momentarily confused, but descriptions draw the boundaries well.

    Naming Consistency4/5

    All tools share a consistent kb_ prefix with mostly verb_noun snake_case names (kb_search, kb_read_document, kb_create_directory, kb_move_file). A couple of names are noun-only (kb_status, kb_log) but they remain readable and predictable.

    Tool Count5/5

    Twelve tools is well within the healthy range and each earns its place: search, read, browse, organize, index maintenance, and auditing. Nothing feels padded or redundant at the set level.

    Completeness3/5

    The lifecycle is covered for browsing, reading, moving, renaming, and index upkeep, plus a health audit. However there is no delete/archive operation and no way to create or write a document/file (only directories), which are noticeable gaps for a file-organizing knowledge base workflow.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      Not graded
      maintenance
      A local-first knowledge base server that enables AI clients to store, retrieve, and manage documents using semantic search. Provides privacy-focused, offline-capable memory for AI assistants with tools for ingesting, querying, updating, and deleting knowledge.
      7
      21 npm
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to capture bookmarks, sticky notes, todos, notes, and web archives, and to search and organize personal knowledge and memory across cloud-synced clients.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables local AI agents to perform hybrid search (BM25 + vector) over privately indexed local files, including notes, PDFs, DOCX, source code, and OCR'd images. All indexing and retrieval stay on the machine with read-only, whitelist-scoped access.
      3
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a local hybrid (vector + BM25) index of scattered notes, docs, PDFs, and chat logs to AI hosts like Claude Desktop, Cursor, and Cline, letting agents search and get cited answers. It publishes a set of tools, resources, and prompts so any MCP-compatible client can query that knowledge base with section-level citations.
      -