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 check my inbox and organize any new files"
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 启动崩溃。
结构化收敛架构:
外置硬盘根目录下仅保留单一
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 工具清单
工具名称 | 功能描述 |
| 报告硬盘挂载状态、分类目录以及已索引文件统计。 |
| 全文/关键词/语义检索,返回命中的文档段落、匹配得分与来源路径。 |
| 增量扫描外置硬盘中的新文件并更新索引库(支持 |
| 扫描 |
| 将文件从一个目录移动到另一个目录,并支持原子化重命名与索引同步。 |
| 对指定文件按标准规则重命名并同步索引。 |
| 在知识库内创建新的分类子目录。 |
| 提取指定文档的全文纯文本(支持 PDF、Word、PPT、EPUB、Markdown 等)。 |
| 获取指定子目录的树状结构(支持深度限制)。 |
| 记录整理流水账到外置硬盘日志中。 |
| 重新生成并原子化覆盖根目录下的 |
| 检查待处理积压、死链、未收录进 |
💬 常用日常提示词模板
1. 【一键整理收件箱】
“请调用
kb_scan_inbox检查外置硬盘_Inbox里的所有新文件:
根据内容为每个文件重命名为
YYYY-MM-DD_[主题]_[关键词].[ext];移动到对应分类目录(如
01_Documents、02_Books等);调用
kb_update_index_md更新根目录索引并调用kb_reindex增量更新检索库。”
2. 【智能检索与问答】
“请在知识库中检索关于‘[关键词/技术点]’的资料,总结核心结论,并注明引用自哪个文件。”
3. 【知识库体检】
“请运行
kb_health_check检查知识库健康状态,并汇报积压与未索引情况。”
📄 开源协议
本项目采用 MIT License 开源协议。
Available Tools
12 toolskb_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_searchA
Search the knowledge base and return the most relevant text chunks.
:param query: Natural-language question or keywords (Chinese/English). :param top_k: Number of chunks to return (1-30). :param mode: "keyword" (BM25/substring), "semantic" (embeddings), or "hybrid" (both, rank-fused). "hybrid" is recommended.
Inputs: query (required), mode, top_k. 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
Scored across 12 tools
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.
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.
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.
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
Personal memory layer: files, notes, messages, tasks and email, semantically indexed.
Your personal library, readable by AI agents: durable snapshots, hybrid search, 46 MCP tools.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Related MCP Servers
- FlicenseAqualityNot gradedmaintenanceA 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.721 npm-
- FlicenseNot gradedqualityCmaintenanceEnables 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.-
- AlicenseAqualityBmaintenanceEnables 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.3MIT
- FlicenseNot gradedqualityAmaintenanceExposes 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.-