secondbrain-mcp
This MCP server exposes a safety-oriented local Markdown knowledge-base gateway for reading, searching, editing, archiving, and restoring notes.
Read a note by vault-relative path and return its content hash; private notes are never readable.
List note paths, excluding private notes, with optional folder/pattern filters.
Run keyword search over indexed notes, with fallback to a linear vault scan if the index is empty.
Run RAG retrieval with per-note scores and traceability fields; excerpts are candidates requiring
read_notebefore citation.Incrementally re-index the vault, optionally forcing rebuild, and inspect index health without exposing note contents.
Create notes in an inbox area without overwriting existing files.
Append to notes under a per-file lock with optimistic concurrency via
expected_hash.Update allowlisted frontmatter metadata fields with optional hash checking.
Move notes within the vault, never into private areas, and only to non-existing destinations.
Archive notes in batches with dry-run support and a rollback manifest.
List archive batches with restore accounting.
Restore archived batches back to original paths, skipping already-restored, missing, altered, or occupied entries.
Serves a local Markdown vault as a personal knowledge base: reads, lists, searches and incrementally indexes notes, creates notes into inbox folders, and modifies notes (append, frontmatter metadata updates, moves) under hash-locked optimistic concurrency, with archive/restore instead of deletion and privacy-zone blocking for private note paths.
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., "@secondbrain-mcp Search my knowledge base for notes about AI safety"
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.
secondbrain-mcp
Local-first personal knowledge base as MCP: Markdown vault + hybrid RAG retrieval + a safety-first gateway with hash locks, audit trail, privacy zones and rollback — so that AI agents can use your knowledge base without being able to wreck it.
状态:✅ v0.2 —— 14 个工具 · 单元+e2e 门禁全绿(含真实 stdio 协议端到端)· CI 门禁全过(semantic 门在 CI 口径外,见评测) | License: MIT
为什么做这个
2026 年的 AI agent 已经很会「读」,但很少被允许「写」用户的长期知识库——因为写没有安全边界。
本项目把一套在个人生产环境真实运行的知识库网关重写为单一 Python 核心,核心是四件事:
哈希锁写入:所有更新必须携带
expected_hash,且在锁内复验;冲突即拒绝并给出恢复指令。无删除设计:归档 = 移动到 Archive 区并生成可回滚清单,清单在移动之前写入。
隐私分区:
95_Private在读取、写入、索引、检索四层拒绝,分区判定大小写无关。全量审计:intent 与 outcome 分开记录,每条带前一条的哈希,形成可校验的链。
Related MCP server: brain-mcp
功能
MCP server:14 个窄工具(read / list / search / index / review / create / append / patch / meta / move / archive / restore / archive_list_batches)
混合检索:BM25 倒排 + 向量余弦 + RRF 融合,两道防噪门禁
增量索引:
embed_state显式跟踪,失败在下一轮自动重试模型指纹:换模型强制重建向量,杜绝向量空间混用
正文编辑:
note_patch两阶段确认,先出 diff 再落盘隐私分区与待确认队列
合成演示知识库(demo vault,无任何真实个人内容)
单元测试 + 对抗性测试 + MCP stdio 端到端 + 可失败的检索门禁
部署健康检查(暂存库跑全契约 + live 索引只读快照探针)
文档
架构总览 — 分层、分区表、索引结构、检索设计
评测方法 — 为什么旧评测报 1.00 而真实只有 60%,以及现在的五道门禁
威胁模型 — 防什么、不防什么、已知限制
迁移记录 — 从 Node 网关迁到 Python 核心的行为变化与回滚方式
快速开始
要求 Python 3.10+。两档安装:
git clone https://github.com/stone1524/secondbrain-mcp
cd secondbrain-mcp
pip install -e ".[semantic]" # 完整混合检索(含 numpy + fastembed,推荐)
pip install -e . # 纯词法模式(无需 numpy,mode=hybrid 自动降级并在返回中说明原因)试用合成 demo vault(不接你自己的数据,仓库自带、全部为合成内容):
secondbrain-mcp # 不设 SB_VAULT_ROOT 时默认服务仓库内 demo-vault/接入自己的知识库 / MCP 客户端(Claude Code、Cursor 等任何支持 MCP 的客户端):
{
"mcpServers": {
"secondbrain": {
"command": "python",
"args": ["-m", "secondbrain_mcp.adapters.mcp_stdio"],
"env": {
"SB_VAULT_ROOT": "C:/path/to/your/markdown-vault",
"SB_STATE_ROOT": "C:/path/to/state",
"SB_AGENT_LABEL": "claude"
}
}
}
}环境变量:
变量 | 默认 | 说明 |
| 仓库内 | vault 目录 |
|
| 索引、审计、锁的根目录 |
|
| 索引库路径 |
| 无 | 审计归因标签,多客户端共用时区分写入者 |
|
| 设为 |
|
| 嵌入模型 |
| 无 | 模型缓存目录(离线场景必填,直通 fastembed) |
|
| 嵌入批大小,直通 fastembed |
|
| 语义命中相似度下限(查询与笔记同语言时) |
|
| 跨中英语言对的语义命中下限(zh 调优模型跨语言余弦偏低,按语言对单独校准) |
|
| 语义命中最小 token 数,按整篇笔记计量(命中分块或全篇分块合计过线均可) |
索引在首次 search 时按需自动构建或修复(大库首次调用会慢);index_rebuild 用于手动/强制重建(换嵌入模型后加 force=true)。note_read 才是取证。
安全模型
写:
note_create默认只进 inbox 且重名加后缀(不覆盖);overwrite=true提供带expected_hash哈希锁的受控覆盖(锁内复验);note_append/note_patch/note_meta/note_move全部要求expected_hash,并在文件锁内复验删:不存在。唯一移除路径是带批次回滚清单的归档,restore 可整批或按条恢复
隐私:私有前缀在读、写目的地、索引、搜索四层拒绝,且大小写无关;泄漏探针在单元与线上两层测试
审计:每次写落
intent与outcome两条,带哈希链;AuditLog.verify()可校验内容即数据:所有读取与检索结果带
trust: untrusted_note,提示调用方不得把笔记内容当作指令
评测
python -m secondbrain_mcp.eval.run --cases eval/cases-dev.json --semantic五道门禁,每一道都能真的失败:recall@5 ≥ 0.85(标题派生用例口径;零重叠探针 no_shared_term 由下述 semantic 门与 by_category 读数单独承担,headline recall 仍计全量)、semantic rank-1 wins ≥ 1(仅在 --semantic 下生效,词法模式报告为 not-applicable 而不是静默通过;CI 无模型缓存、从不跑 --semantic,向量通道在 CI 口径中为 uncovered)、null vectors == 0、privacy leakage == 0(读侧四种拼写探测)、index_side_leak == 0(直接读库,抓读侧门禁看不见的入库泄漏)。CI 会先建 demo 索引,再跑门禁与部署契约检查,并再生成 eval/cases-dev.json 与提交版本比对(用例文件不得滞后 policy 变更)。
当前结果与旧系统的对照见 docs/evaluation.md。
开发方式:AI 结对 + 测试门禁
本仓库以「AI agent 结对 + 人工把关」的方式开发:agent 负责起草与重构,人负责审查与取舍,所有提交前必须通过同一组门禁——
pytest -q:357 条用例(单元 + 对抗 + MCP stdio 端到端),本地实跑通过才允许提交ruff静态检查GitHub Actions:双平台 × 双版本矩阵,main 分支保留全矩阵通过记录(2026.10.20 Run 5 可查)
38 次提交均由本人逐个确认——AI 提升的是速度,边界与取舍仍由人决定。这也是本项目主题(让 AI 安全地参与真实工作)在开发过程本身上的实践。
License
MIT
Available Tools
13 toolsappend_noteB
Append to a note under a per-file lock with optimistic-concurrency check on expected_hash.
Inputs: note (required), content (required), expected_hash.
archive_notesA
Archive notes by (note, hash, category) entries into the review area with a batch rollback manifest. Run dry_run first.
Inputs: entries (required), dry_run.
create_inbox_noteA
Create a note in an inbox directory (Web/Conversations/Files). Never overwrites an existing file.
Inputs: folder (required), content (required), filename (required).
list_archivesB
List archive batches with their restore accounting.
Inputs: limit.
list_notesA
List note paths (private notes excluded), newest first; optional folder prefix and substring pattern.
Inputs: limit, folder, pattern.
move_noteA
Move a note within the vault (never into a private area); destination must not exist.
Inputs: note (required), destination (required), expected_hash.
rag_reindexC
Incrementally re-index the vault into a rebuildable derived index.
Inputs: force.
rag_searchB
Retrieval with per-note scores and traceability fields. Excerpts are candidates: call read_note before citing.
Inputs: query (required), limit, paths.
rag_statusA
Index health metadata (document/chunk counts, schema version) without exposing note contents.
Inputs: no named parameters.
read_noteA
Read a standard note by vault-relative path; returns the full-content hash. Private notes are never readable.
Inputs: note (required), offset, max_length.
restore_archiveB
Restore an archived batch back to its original paths; skips already-restored, missing, altered or occupied entries.
Inputs: only, dry_run, batch_id.
search_notesA
Keyword search over indexed notes; falls back to a linear vault scan when the index is empty.
Inputs: query (required), limit, paths.
update_metadataA
Update an allowlisted set of frontmatter fields (status/tags/agent_generated/...); other keys are dropped.
Inputs: note (required), fields (required), expected_hash.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools are clearly separated by action and resource, and the archive/restore group is unambiguous. However, search_notes and rag_search both offer retrieval over notes, and list_notes' substring filter partially overlaps with search_notes, so an agent could occasionally pick the wrong one.
Tool names follow a consistent snake_case verb_noun pattern: read_note, list_notes, move_note, append_note, update_metadata, archive_notes, restore_archive. The rag_* tools use a domain prefix but still read predictably, so the naming convention is coherent throughout.
Thirteen tools is a well-scoped count for a note-management server covering capture, retrieval, organization, metadata, and archiving. Each tool has a clear role and none feel redundant or extraneous.
The core note lifecycle is well covered: create via inbox, read, list, search, move, append, metadata update, archive, and restore. The main gaps are the lack of a direct content-replacement operation and a permanent delete/purge, though append and archive/restore mitigate most practical needs.
Maintenance
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Markdown notes and whiteboards your AI agent can read and write.
Shared Markdown memory for your agents: docs, typed collections, files, skills and Dispatch.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read and write a local-first knowledge base of plain markdown files in git, with governance gates for safe, hash-anchored edits.1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to securely read and write to an Obsidian-compatible Markdown vault with per-agent access control, audit logging, and conflict resolution.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceTurns a folder of Markdown notes into an agent-native knowledge base, providing long-term memory with provenance, token-budgeted retrieval, and safe write-back with versioning.MIT
- AlicenseAqualityDmaintenanceEnables AI agents to maintain a persistent, queryable memory stored as user-owned Markdown files, with dual-channel retrieval (FTS5 and optional semantic search) and an audited write pipeline.11MIT