KnowledgeBase MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@KnowledgeBase MCP search my notes for anything about the Paris trip"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
📚 KnowledgeBase MCP (kb-mcp)
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 工具清单
工具名称 | 功能描述 |
| 报告硬盘状态(细分到未挂载/只读/无权限/无响应等)、索引统计与后台任务进度;永不报错。 |
| 一步收录文字:存成 |
| 从本机导入文件或文件夹(下载/桌面/文稿/~/Claude/iCloud,及 |
| 关键词/语义检索:空格分隔的词需同时出现(都没有时按命中词数排序),也匹配文件名; |
| 提取文档全文(PDF、Word、PPT、EPUB、Markdown 等),长文用 |
| 列出 |
| 批量移动/重命名(一次最多 200 个),索引同步、 |
| 移动/重命名单个文件(不写扩展名时保留原扩展名)。 |
| 原地重命名并同步索引。 |
| 可恢复地删除:移到 |
| 按内容指纹找出重复文件。 |
| 在知识库内创建新的分类子目录。 |
| 目录树(深度限制,最多 600 行)。 |
| 全盘扫描更新索引( |
| 体检:收件箱积压、 |
| 立即重写 |
| 记录整理流水账到外置硬盘日志中。 |
kb-files 另外提供官方文件服务的全部工具(read_text_file、write_file、list_directory、move_file 等),外加它自己的 kb_status。
🩺 状态与故障诊断
两个服务的 kb_status 都会返回 state 字段,不是 ok 时附带 hint 告诉你怎么处理:
state | 含义 | 处理 |
| 已挂载、可读写 | — |
| 硬盘没插或没挂载 | 插上即可,无需重启 Claude |
| 路径是系统盘上的残留文件夹,不是外置硬盘 | 推出硬盘、删掉残留文件夹后重插; |
| 硬盘已挂载,但找不到 | 是否插错盘、改了名,或还没运行 |
| 系统拒绝访问 | 系统设置 → 隐私与安全性 → 文件与文件夹 → 允许 Claude 访问“可移除的宗卷” |
| 只读挂载 | 检索、读取照常可用,写入会被拒绝;用“磁盘工具”急救后重插 |
| 硬盘已满 | 清理空间 |
| 检查在超时内没完成(休眠、接触不良、正在推出) | 稍等重试,持续出现就重新插拔 |
| 其他读写错误 | 重新插拔,必要时“磁盘工具”急救 |
这一版专门针对「拿不到状态」做了加固:
晚插硬盘不用重启:Claude Desktop 只在启动时读取一次工具列表,并且会忽略后续的列表变更通知。所以
kb-files改由fs_gateway.py常驻代理:始终声明完整的文件工具,硬盘可用时才在第一次调用时拉起官方文件服务;文件服务崩溃了,下一次调用会自动重启它。状态永不卡死:所有耗时操作都放到工作线程里跑,重建索引、读大 PDF 时
kb_status照样秒回;硬盘检查有超时(默认 4 秒),超时报unresponsive,不会一直挂着。拔盘不崩溃:SQLite 的 WAL 模式会内存映射
-shm文件,硬盘被拔掉时 macOS 会用 SIGBUS 直接杀掉进程。索引库因此改用回滚日志(journal_mode=DELETE,旧索引首次打开时自动转换)并关闭 mmap;每次操作单独开、关连接,拔插后不会残留失效的连接。拔盘不丢索引:重建分批提交;中途断开或有目录读不了时,不会把读不到的文件当成“已删除”清出索引。
可选环境变量:
变量 | 默认 | 作用 |
|
| 知识库根目录 |
|
| 硬盘检查超时(秒) |
| 路径在 | 要求路径确实在外置卷上(防止写进系统盘残留文件夹) |
|
| 设为 |
|
| 官方文件服务启动超时(秒) |
|
| kb-files 工具列表缓存位置 |
|
| 索引库日志模式(不建议改回 |
|
| 启动和重新插盘时后台补扫索引; |
| (空) |
|
|
| 官方文件服务的固定版本(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,可以直接选这四个现成指令:
指令 | 作用 |
一键整理收件箱 | 扫描 |
收录到知识库 | 文字用 |
知识库体检 |
|
检索知识库 | 多关键词检索并注明出处 |
也可以直接说,例如:
“把这段会议记录收进知识库,放 03_Notes,标签:会议、硬盘。”
“把下载文件夹里的《季度报告.pdf》导入到 01_Documents。”
“在知识库里找 2026 年硬件预算相关的资料,注明出处。”
📄 开源协议
本项目采用 MIT License 开源协议。
Available Tools
17 toolskb_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_searchA
Search the knowledge base and return the most relevant text chunks.
Space-separated words must all appear (if nothing has all of them, chunks with the most words are returned, source="keyword-partial"). File names are matched too (source="filename").
:param query: Keywords or a question, e.g. "预算 硬件 2026". :param top_k: Number of chunks to return (1-30). :param mode: "keyword", "semantic" (needs KB_ENABLE_SEMANTIC) or "hybrid". :param folder: Optional sub-folder to search in, e.g. "02_Books".
Inputs: query (required), mode, top_k, folder. 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
Scored across 17 tools
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.
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.
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.
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
Related MCP Connectors
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Personal context for every AI: search, read, and write back to your private Markdown library.
Personal memory layer: files, notes, messages, tasks and email, semantically indexed.
Persistent memory for AI agents. Hosted cloud connector or local Windows install.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables 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-
- AlicenseNot gradedqualityDmaintenanceA 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
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to file notes into a self-hosted Obsidian vault and retrieve them later through structured and semantic search over plain Markdown.MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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