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 启动崩溃。

    • 晚插、拔插、只读挂载都不用重启 Claude:插上硬盘后下一次调用立即可用(见下方「状态与故障诊断」)。

  • 结构化收敛架构:

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

  • 混合检索能力:

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

  • 一步收录、即时可搜:

    • kb_add_note 把文字/数据存成规范命名的 Markdown,kb_import_file 从「下载」「桌面」「文稿」导入文件或整个文件夹;存完立刻能搜到,不必全盘重建索引。

    • 按内容指纹(SHA-256)自动去重,重复收录会直接告诉你已有的那一份。

  • AI 智能整理工作流:

    • kb_scan_inbox 看收件箱 → kb_organize 一次调用批量命名归档;kb_trash 可恢复地删除;INDEX.md 每次改动后自动刷新。

    • 用访达直接拖进硬盘的文件,插盘时后台自动补进索引。


Related MCP server: Notes MCP Server

🚀 方式一:直接使用 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": "uvx",
      "args": [
        "--from",
        "git+https://github.com/admin0330/kb-mcp.git",
        "kb-files-gateway",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-filesystem",
        "/Volumes/KnowledgeBase/Database"
      ],
      "env": {
        "KB_VOLUME": "/Volumes/KnowledgeBase/Database"
      }
    }
  }
}

kb-files-gateway 包在官方文件服务外面:硬盘没插时 Claude Desktop 照样能启动,插上后无需重启即可读写。 直接用 npx … server-filesystem 也能跑,但启动时硬盘不在就会直接退出,之后要重启 Claude Desktop 才能恢复。

提示:如果需要启用向量语义检索,只需在 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 独立虚拟环境;有 npm 时顺带装一份固定版本的
#    官方文件服务到 server/node,kb-files 启动更快、断网也能用)
./scripts/setup.sh

# 3. 初始化外置硬盘目录结构 (首次使用;参数是知识库根目录,即 Database 文件夹)
./scripts/init_drive.sh /Volumes/KnowledgeBase/Database

然后在 claude_desktop_config.json 里把两个服务指向 scripts/ 下的启动脚本(参考 config/claude_desktop_config.json,把路径换成你的克隆位置)。启动脚本会根据自身位置找到仓库,不依赖固定的用户目录。


📂 外置硬盘标准目录规范

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

🧰 提供的 MCP 工具清单

工具名称

功能描述

kb_status

报告硬盘状态(细分到未挂载/只读/无权限/无响应等)、索引统计与后台任务进度;永不报错。

kb_add_note

一步收录文字:存成 YYYY-MM-DD_标题.md(带标签/出处),立即可搜,内容重复会提示。

kb_import_file

从本机导入文件或文件夹(下载/桌面/文稿/~/Claude/iCloud,及 KB_IMPORT_DIRS),可选 move,自动去重。

kb_search

关键词/语义检索:空格分隔的词需同时出现(都没有时按命中词数排序),也匹配文件名;folder= 限定目录。

kb_read_document

提取文档全文(PDF、Word、PPT、EPUB、Markdown 等),长文用 start_char 分页读。

kb_scan_inbox

列出 _Inbox/ 待整理文件和内容预览(limit 控制数量)。

kb_organize

批量移动/重命名(一次最多 200 个),索引同步、INDEX.md 自动刷新。

kb_move_file

移动/重命名单个文件(不写扩展名时保留原扩展名)。

kb_rename_file

原地重命名并同步索引。

kb_trash

可恢复地删除:移到 _Trash/<日期>/,从检索和 INDEX.md 中移除。

kb_find_duplicates

按内容指纹找出重复文件。

kb_create_directory

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

kb_list_tree

目录树(深度限制,最多 600 行)。

kb_reindex

全盘扫描更新索引(full=True 全量重建)。平时很少需要:新增/移动的文件即时索引,插盘时也会自动补扫。后台运行,进度看 kb_status。

kb_health_check

体检:收件箱积压、INDEX.md 遗漏/死链、未入索引的文本文件;fix=True 自动修复。

kb_update_index_md

立即重写 INDEX.md(平时会自动刷新)。

kb_log

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

kb-files 另外提供官方文件服务的全部工具(read_text_file、write_file、list_directory、move_file 等),外加它自己的 kb_status。


🩺 状态与故障诊断

两个服务的 kb_status 都会返回 state 字段,不是 ok 时附带 hint 告诉你怎么处理:

state

含义

处理

ok

已挂载、可读写

—

not_mounted

硬盘没插或没挂载

插上即可,无需重启 Claude

phantom_dir

路径是系统盘上的残留文件夹,不是外置硬盘

推出硬盘、删掉残留文件夹后重插;candidates 会列出硬盘实际挂载的位置(如 KnowledgeBase 1)

kb_dir_missing

硬盘已挂载,但找不到 Database 文件夹

是否插错盘、改了名,或还没运行 init_drive.sh

permission_denied

系统拒绝访问

系统设置 → 隐私与安全性 → 文件与文件夹 → 允许 Claude 访问“可移除的宗卷”

read_only

只读挂载

检索、读取照常可用,写入会被拒绝;用“磁盘工具”急救后重插

disk_full

硬盘已满

清理空间

unresponsive

检查在超时内没完成(休眠、接触不良、正在推出)

稍等重试,持续出现就重新插拔

io_error

其他读写错误

重新插拔,必要时“磁盘工具”急救

这一版专门针对「拿不到状态」做了加固:

  • 晚插硬盘不用重启:Claude Desktop 只在启动时读取一次工具列表,并且会忽略后续的列表变更通知。所以 kb-files 改由 fs_gateway.py 常驻代理:始终声明完整的文件工具,硬盘可用时才在第一次调用时拉起官方文件服务;文件服务崩溃了,下一次调用会自动重启它。

  • 状态永不卡死:所有耗时操作都放到工作线程里跑,重建索引、读大 PDF 时 kb_status 照样秒回;硬盘检查有超时(默认 4 秒),超时报 unresponsive,不会一直挂着。

  • 拔盘不崩溃:SQLite 的 WAL 模式会内存映射 -shm 文件,硬盘被拔掉时 macOS 会用 SIGBUS 直接杀掉进程。索引库因此改用回滚日志(journal_mode=DELETE,旧索引首次打开时自动转换)并关闭 mmap;每次操作单独开、关连接,拔插后不会残留失效的连接。

  • 拔盘不丢索引:重建分批提交;中途断开或有目录读不了时,不会把读不到的文件当成“已删除”清出索引。

可选环境变量:

变量

默认

作用

KB_VOLUME

/Volumes/KnowledgeBase/Database

知识库根目录

KB_PROBE_TIMEOUT

4

硬盘检查超时(秒)

KB_REQUIRE_EXTERNAL

路径在 /Volumes/ 下时为 1

要求路径确实在外置卷上(防止写进系统盘残留文件夹)

KB_FS_GATEWAY

1

设为 0 恢复旧的 kb-files 启动方式

KB_FS_START_TIMEOUT

45

官方文件服务启动超时(秒)

KB_CACHE_DIR

~/.cache/kb-mcp

kb-files 工具列表缓存位置

KB_SQLITE_JOURNAL

DELETE

索引库日志模式(不建议改回 WAL)

KB_AUTO_REINDEX

1

启动和重新插盘时后台补扫索引;0 关闭

KB_IMPORT_DIRS

(空)

kb_import_file 额外允许读取的目录,用 : 分隔

KB_FS_VERSION

2.0.1

官方文件服务的固定版本(setup.sh 与 npx 回退都用它)

测试:

python3 -m unittest tests/test_health.py tests/test_indexer.py   # 纯标准库,任何系统
server/.venv/bin/python tests/e2e_macos.py                       # macOS:用临时磁盘镜像模拟插拔
server/.venv/bin/python tests/e2e_features_macos.py              # macOS:收录/导入/整理/回收站等功能

💬 常用指令

在 Claude Desktop 的输入框点 “+” → kb-retrieval,可以直接选这四个现成指令:

指令

作用

一键整理收件箱

扫描 _Inbox,命名归档,一次 kb_organize 搞定并列表汇报

收录到知识库

文字用 kb_add_note、本机文件用 kb_import_file,重复会提醒

知识库体检

kb_status + kb_health_check(fix=True) + kb_find_duplicates

检索知识库

多关键词检索并注明出处

也可以直接说,例如:

“把这段会议记录收进知识库,放 03_Notes,标签:会议、硬盘。”

“把下载文件夹里的《季度报告.pdf》导入到 01_Documents。”

“在知识库里找 2026 年硬件预算相关的资料,注明出处。”


📄 开源协议

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

Available Tools

17 tools
kb_add_noteA

Save text in one step: notes, pasted data, a summary, a web clip, a chat excerpt.

Writes <category>/<YYYY-MM-DD>_<title>.md with a small YAML header, makes it searchable immediately and refreshes INDEX.md. If a note with the same content already exists, nothing is written and its path is returned (duplicate: true) unless allow_duplicate is set.

:param title: Short title; also used for the file name. :param content: The body (Markdown or plain text). :param category: Target folder, e.g. "_Inbox", "03_Notes", "01_Documents/财务" (created if missing). :param tags: Optional tags, e.g. ["预算", "2026"]. :param source: Optional origin: a URL, "微信聊天", a book title ... :param date: Optional YYYY-MM-DD for the file name (default: today).

Inputs: title (required), content (required), date, tags, +3 more. Returns: result

kb_create_directoryB

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

Inputs: relpath (required). Returns: result

kb_find_duplicatesA

List groups of files with identical content (SHA-256), largest first.

Keep one of each group and remove the others with kb_trash.

Inputs: limit. Returns: result

kb_health_checkA

Audit the knowledge base; with fix=True also repair what it can.

Reports: files still in _Inbox (backlog), files missing from INDEX.md (orphans), INDEX.md links to missing files (dead links) and text files not yet in the search index. fix=True indexes the missing files and rewrites INDEX.md, then reports again. The inbox backlog is left for you to organise.

Inputs: fix, max_items. Returns: result

kb_import_fileA

Copy a file or a whole folder from this Mac into the knowledge base.

Allowed sources: ~/Downloads, ~/Desktop, ~/Documents, ~/Claude, iCloud Drive, plus folders listed in KB_IMPORT_DIRS. Text-bearing files (PDF, Word, PPT, EPUB, Markdown ...) are searchable immediately; other files (images, video) are stored and listed in INDEX.md. Files whose exact content is already on the drive are skipped (skipped_duplicates).

:param source_path: Absolute path, e.g. "~/Downloads/报告.pdf" or a folder. :param category: Target folder on the drive (default "_Inbox"). :param new_name: Optional new name (a file's extension is kept if omitted). :param move: Delete the source after a successful copy (default: keep it). :param allow_duplicate: Import even if identical content already exists.

Inputs: source_path (required), move, category, new_name, +1 more. Returns: result

kb_list_treeB

List the directory tree under subdir (depth-limited, max 600 lines).

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_fileA

Move (and optionally rename) one file or folder. For many, use kb_organize.

Also restores items from _Trash. The search index is kept in sync and INDEX.md refreshes automatically.

:param src_rel: Current path, e.g. _Inbox/report.pdf or a folder. :param dest_dir_rel: Target directory, e.g. 01_Documents. :param new_name: Optional new filename; the extension is kept if omitted.

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

kb_organizeA

Move/rename many files in ONE call (e.g. everything from kb_scan_inbox).

Each item: {"src": "_Inbox/a.pdf", "dest_dir": "02_Books", "new_name": "2026-10-28_书名_作者.pdf"} -- new_name is optional. Items are processed independently; failures are reported per item. Up to 200 items per call.

Inputs: moves (required). Returns: result

kb_read_documentA

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

Long documents are paged: when next_start_char is present, call again with start_char set to it to continue reading.

:param relpath: Path relative to the volume root, e.g. 02_Books/foo.pdf. :param max_chars: Maximum characters to return (1-50000). :param start_char: Offset to start from (for paging through long texts).

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

kb_reindexA

Scan the whole drive and bring the search index up to date.

Rarely needed: added/imported/moved files are indexed immediately, and a catch-up scan runs by itself whenever the drive is plugged in. Use it after copying many files onto the drive with Finder, or with full=True to rebuild. Runs in the background; this call waits up to wait_seconds (0-50) and otherwise returns progress -- follow it with kb_status.

:param full: When true, re-extract every file instead of only changed ones. :param wait_seconds: How long to wait for completion before returning.

Inputs: full, wait_seconds. 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.

Decide a category and a name for each, then move them all with ONE :func:kb_organize call. Returns at most limit items per call.

Inputs: limit, preview_chars. Returns: result

kb_statusA

Report the knowledge-base drive state, index statistics and job progress.

Always answers (never errors) within a few seconds. state is one of: ok, not_mounted, phantom_dir, kb_dir_missing, permission_denied, read_only, disk_full, unresponsive, io_error. When it is not ok, hint says what the user should do.

Inputs: no named parameters. Returns: result

kb_trashA

Remove a file or folder from the knowledge base -- recoverably.

It is moved to _Trash/<today>/ (not indexed, not in INDEX.md). Restore with kb_move_file; empty _Trash in Finder when you are sure.

:param relpath: e.g. "03_Notes/重复的笔记.md". :param reason: Optional note for the organize log (e.g. "duplicate of ...").

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

kb_update_index_mdA

Regenerate the root INDEX.md now (it also refreshes automatically).

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

    A3.6/5.0

    Scored across 17 tools

    Disambiguation4/5

    Most tools target clearly distinct actions (read vs search vs list vs status), and descriptions explicitly cross-reference alternatives ("For many, use kb_organize"). The only real overlap is kb_move_file / kb_rename_file / kb_organize, since move_file can also rename, plus some conceptual overlap between kb_reindex, kb_update_index_md and kb_health_check's fix mode — but the descriptions disambiguate each case well.

    Naming Consistency4/5

    All names share a kb_ prefix and nearly all follow verb_noun (kb_read_document, kb_import_file, kb_find_duplicates, kb_update_index_md). Minor deviations are noun-only names like kb_status and kb_log, which break the pattern slightly but remain readable and predictable.

    Tool Count4/5

    17 tools is on the high side of the ideal 3-15 range, but each maps to a real operation in a file-plus-index knowledge base (read, search, import, organize, dedupe, audit). Nothing looks like filler, though a few index-maintenance tools could conceivably be folded together.

    Completeness4/5

    The surface covers the full lifecycle: ingest (import/add_note), discover (search/list/scan), organize (move/rename/organize/create_directory), remove (trash/duplicates), and maintain (reindex/index/health/log). The main gap is editing the content of an existing document in place — there is create and read but no update-body operation — which agents would have to work around by adding a new note and trashing the old one.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      Enables indexing and retrieving notes with full-text search using SQLite, plus building knowledge graphs to find relationships between concepts. Supports natural language note management, tagging, and semantic connections.
      16
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A local note-taking server that provides intelligent management of markdown files through hybrid keyword and AI-powered semantic search. It enables users to create, find, and retrieve notes using advanced indexing, vector embeddings, and a built-in web viewer.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to persist and retrieve notes, code entities, and typed links in a local graph database across sessions, with hybrid offline search, graph traversal, and staleness checks. It also supports export/import and CLI access for backup and transfer.
      MIT