notes-mcp
只读访问本地 Markdown 笔记,用于检索、阅读、浏览最近修改、统计语料,并提供索引资源和周总结提示模板。
搜索笔记:用关键词全文检索,返回命中行上下文片段,每篇最多 3 段、总预算 8000 字符。
读取笔记:按根目录相对路径读取单篇全文,超过 20000 字符截断,并拒绝越界路径和根外符号链接。
列出最近笔记:列出最近 N 天修改过的笔记路径、修改时间和首行标题,默认 7 天。
查看笔记统计:返回笔记总数、总字数、
#tag标签分布和最近修改时间。读取资源:通过
notes://index获取全部笔记清单,通过notes://note/{+path}读取单篇正文。使用提示模板:用
weekly-review生成“总结本周关于 {topic} 的笔记”的指令。
Provides read-only access to local Markdown note directories, enabling full-text search, reading individual notes, listing recently modified notes, and generating note statistics such as note counts, word counts, and tag distribution.
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., "@notes-mcp search my notes for anything about the Q4 roadmap"
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.
notes-mcp
把本地 Markdown 笔记目录以只读方式暴露给 AI 助手的 MCP Server。
基于 MCP 规范 2026-07-28,Python SDK mcp[cli] >= 2.0。
不写文件、不删文件、不执行任何外部命令。所有返回值都有字符预算上限。
它提供什么
Tools(模型调用)
名称 | 参数 | 行为 |
|
| 全文检索,返回命中行 ±2 行的片段(每篇最多 3 段),总预算 8000 字符 |
|
| 读取单篇全文,超过 20000 字符截断并标注 |
|
| 最近 N 天修改过的笔记(路径 + 时间 + 首行标题) |
|
| 按修改时间倒序翻页列出全部笔记, |
| — | 笔记总数、总字数、标签分布(解析 |
Resources(客户端/用户读取)
URI | 说明 |
| 全部笔记清单(JSON:uri / path / title / mtime / units / tags) |
| 单篇笔记正文,例如 |
Prompts(用户触发的模板)
名称 | 参数 | 说明 |
|
| 生成"总结本周关于 {topic} 的笔记"的指令,要求 3 条要点 + 出处 |
Related MCP server: MCP Notes Server
快速开始
# 方式一:uv(推荐,与文档命令一致)
uv sync
uv run notes-mcp --root ./sample_notes
# 方式二:pip 可编辑安装
python -m venv .venv
.venv/Scripts/python -m pip install -e . # Windows
# .venv/bin/python -m pip install -e . # macOS / Linux
.venv/Scripts/python -m notes_mcp --root ./sample_notes--root 也可以省略,此时按 NOTES_MCP_ROOT 环境变量 → ./notes 的顺序取值。
构建可分发的产物
uv build # -> dist/notes_mcp-0.1.0-py3-none-any.whl 与 dist/notes_mcp-0.1.0.tar.gz把 wheel 拷到目标机器(不需要源码、不需要 uv):
python -m venv .venv
.venv/Scripts/python -m pip install notes_mcp-0.1.0-py3-none-any.whl
.venv/Scripts/notes-mcp --root D:\Notes --version装完就多了一个 notes-mcp 命令,客户端配置里直接指向它,不用再记 python -m notes_mcp。
CI(.github/workflows/ci.yml)在每次推送时都会走一遍"构建 → 装进干净 venv → 跑 --version",
所以"构建成功"和"装得上"这两件事不会脱节。
验收(Inspector CLI,强制 modern 协议)
npx @modelcontextprotocol/inspector@2.12.0 --cli \
--protocol-era modern \
uv run notes-mcp --root ./sample_notes \
--method tools/list看到五个工具名即通过。--protocol-era modern 不能省——Inspector 的 CLI 在
ad-hoc 目标下默认走 legacy(2025 握手),不加这个参数你测的是旧时代的行为。
本地完整自检
uv run python scripts/verify.py # 走真实 stdio 客户端,跑全部工具/资源/提示
uv run pytest # 单元测试 + 端到端测试三条工程约束
1. 路径安全
read_note 的 path 来自模型,是不可信输入。校验流程(notes_mcp/safety.py):
拒绝空、NUL 字节;
拒绝绝对路径(同时覆盖 POSIX
/x、WindowsC:\x、\\server\share);拒绝任何含
..的路径;Path.resolve()展开符号链接之后,用is_relative_to(root)判断是否越界;只允许
.md/.markdown。
第 4 步是唯一真正有效的一步。字符串里看不出问题的 escape.md 完全可能是个
指向 C:\Windows\System32\drivers\etc\hosts 的软链接——只有 resolve 之后再比较才拦得住。
2. 上下文预算
search_notes 绝不返回整篇。每个片段前后各 2 行、每篇最多 3 段、总预算 8000 字符。
超限时返回文本里会带 [已截断:…],明确告诉模型"你还没看完"。
完整预算表见 docs/WALKTHROUGH.md 的 S4 一节。
3. 结构化错误
工具失败时不抛裸异常,而是 raise ToolError("路径越界:…。只允许笔记根目录内的相对路径")。
客户端收到 isError: true + 可读文本,模型能据此改写参数重试。
抛未捕获异常的话,模型只会看到 Error executing tool read_note,学不到任何东西。
接入客户端
Claude Desktop
编辑 %APPDATA%\Claude\claude_desktop_config.json(macOS:~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"notes": {
"command": "C:\\Users\\<你>\\projects\\notes-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "notes_mcp", "--root", "D:\\Notes"]
}
}
}macOS / Linux 上 command 换成 .venv/bin/python 的绝对路径(Linux 把 /Users/<你> 换成 /home/<你>):
{
"mcpServers": {
"notes": {
"command": "/Users/<你>/projects/notes-mcp/.venv/bin/python",
"args": ["-m", "notes_mcp", "--root", "/Users/<你>/Notes"]
}
}
}三个必须注意的点:
Windows 路径在 JSON 里要用双反斜杠,否则
\U、\n会被当转义序列;用
.venv里 python 的绝对路径,不要写uv run——Claude Desktop 不继承你的 shell 环境, 找不到uv就静默失败;改完必须完全退出 Claude Desktop(托盘图标也要退),它只在启动时读配置。
Cursor
~/.cursor/mcp.json(项目级用 .cursor/mcp.json),结构同上:
{
"mcpServers": {
"notes": {
"command": "C:\\Users\\<你>\\projects\\notes-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "notes_mcp", "--root", "D:\\Notes"]
}
}
}macOS / Linux 上 command 同样换成 .venv/bin/python 的绝对路径(Linux 把 /Users/<你> 换成 /home/<你>):
{
"mcpServers": {
"notes": {
"command": "/Users/<你>/projects/notes-mcp/.venv/bin/python",
"args": ["-m", "notes_mcp", "--root", "/Users/<你>/Notes"]
}
}
}在 Cursor 的 Settings → MCP 里确认 notes 显示为已连接、工具数为 5。
用 wheel 装好的命令
如果是 pip install notes_mcp-*.whl 装的,直接指向虚拟环境里的可执行文件更省事:
{
"mcpServers": {
"notes": {
"command": "C:\\Users\\<你>\\notes-venv\\Scripts\\notes-mcp.exe",
"args": ["--root", "D:\\Notes"]
}
}
}macOS / Linux 上 command 换成 /Users/<你>/notes-venv/bin/notes-mcp。
配置项
环境变量 | 默认值 | 说明 |
|
| 笔记根目录 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 每篇笔记最多返回几个片段 |
|
| 每个命中行前后各带几行上下文 |
|
| 单个片段最多多少行 |
|
|
|
所有整数字段必须为正整数(Settings.__post_init__ 校验),
环境变量解析失败或为非正数时退回默认值;显式参数优先于环境变量。
命令行参数:--root、--transport {stdio,streamable-http}、--host、--port、
--stateless-http、--log-level。
完整的实施过程(每个阶段的协议报文、验收输出、踩过的坑)见
docs/WALKTHROUGH.md。
项目结构
notes_mcp/
├── config.py 运行期配置(根目录 + 各类预算)
├── errors.py 共享异常类型(PathRejected,避免循环导入)
├── safety.py 不可信路径校验(工具与资源共用同一套规则)
├── notes/ 扫描 / 解析 / 片段化检索 / 存储(原 store.py 的拆分)
│ ├── models.py Note / Fragment / NoteHit
│ ├── scan.py 扫描候选笔记文件 + 后缀白名单
│ ├── parse.py 标题 / 标签 / 字数等纯文本解析
│ ├── search.py 子串检索 + 片段合并 + 渲染
│ └── store.py NoteStore 协议 + 朴素文件系统实现
├── store.py 兼容层(已废弃):re-export notes/,一个版本后删除
├── budget.py 截断与预算拼装
├── tools/ 四个 Tool 的纯逻辑(不认识 MCP,可单测,原 tools.py 的拆分)
│ ├── search.py / read.py / recent.py / stats.py / common.py
├── services/
│ └── read_note.py 读单篇的唯一实现(Tool 与 Resource 共用)
├── resources.py 两个 Resource 的纯逻辑
├── prompts.py Prompt 模板
├── server.py 注册到 MCPServer
└── __main__.py 进程入口:参数、stderr 日志、传输分层的关键是 tools.py / resources.py 不 import 任何 MCP 的东西。
它们只接收 Settings 和字符串,抛 PathRejected / QueryRejected;
server.py 才把这些异常翻译成 ToolError / ResourceNotFoundError。
这样单测不需要起 server,也不用解析 JSON-RPC。
故障排查
现象 | 判断依据 | 处理 |
客户端显示 "Server disconnected" | stderr 里有 traceback | 直接跑 |
工具列表是空的 | Inspector 没加 | 加上参数重测 |
客户端读到一半乱码 | stdout 混入了非协议输出 | 检查是否有 |
| 路径相对的是根目录,不是当前目录 | 先读 |
已知限制
朴素检索:每次调用都全量扫描并读盘。几千篇以内无感,10 万篇需要倒排索引 (改造方向见
docs/WALKTHROUGH.mdS1 后半段)。只读:没有任何写路径。需要写入请另开一个 server,并显式做权限与备份。
单进程单根目录:一个进程只服务一个
--root。多个目录就配多个 server 条目。不要把
--host设成0.0.0.0:streamable-http 默认只监听127.0.0.1(本机)。 一旦绑到0.0.0.0,局域网内任何人都能读你的笔记——这个 server 没有认证。符号链接:扫描跟随解析后仍在根目录内的链接(文件链接与目录链接都一样), 指向根外的链接会被跳过;循环链接(A→B→A)会被去重,不会无限递归; 两个链接指向同一目录时,同一篇笔记只出现一次。
read_note对根外链接同样拒绝。 根内链接仍可正常读取。
开发
uv sync # 含 dev 依赖(pytest / anyio)
uv run pytest # 单元测试 + 端到端测试
uv run python scripts/verify.py # 端到端检查(真实 stdio + 报文纯净度)
uv run python scripts/budget_report.py # 打印各类返回的实测体积,确认没越预算
uv run python scripts/demo_weekly_review.py # 按 prompt 模板走一遍完整调用链实施过程与逐阶段协议报文见 docs/WALKTHROUGH.md,
可复现的验收结论见 docs/project-brief.md(历史快照)。
许可证
Available Tools
4 toolslist_recentA
列出最近 N 天内修改过的笔记(相对路径 + 修改时间 + 首行标题),按修改时间倒序。适合回答'上周我写了什么'这类问题。
Inputs: days.
notes_statsA
返回笔记总数、总字数、标签分布(解析正文里的 #tag)和最近修改时间。用于先摸清语料规模。
Inputs: no named parameters.
read_noteA
读取单篇笔记的完整正文。path 必须是相对笔记根目录的路径(如 daily/2026-10-01.md),超过 20000 字符会截断并在末尾标注。绝对路径、.. 和指向根目录外的符号链接都会被拒绝。
Inputs: path (required).
search_notesA
按关键词全文检索本地笔记,返回命中行前后各若干行的片段(每篇最多 3 段),总长度不超过 8000 字符。适合先定位再精读;不要用它读整篇笔记,那是 read_note 的职责。
Inputs: query (required), limit.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: search_notes returns snippets, read_note returns full content, list_recent lists recently modified notes, and notes_stats summarizes corpus metadata. The descriptions explicitly clarify boundaries, especially search versus read.
Three tools follow a verb_object pattern (search_notes, read_note, list_recent), while notes_stats is noun_noun. The deviation is minor and still readable, but it breaks strict consistency.
Four tools are well-scoped for a focused notes retrieval server. Each tool earns its place and covers a distinct query pattern without bloat.
The read-only surface covers search, full read, recent listing, and stats, but there are no create, update, append, or delete operations. For a notes server, this is a notable gap if agents are expected to manage notes rather than only inspect them.
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Personal context for every AI: search, read, and write back to your private Markdown library.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only toolkit for searching and analyzing Markdown note directories and Obsidian vaults through AI clients. It enables metadata extraction, full-text search, and natural language querying of note content, tags, and backlinks.4AGPL 3.0
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with a local folder of Markdown notes, supporting listing, reading, searching, creating, and appending to notes with strict security boundaries.5MIT
- AlicenseNot gradedqualityCmaintenanceProvides controlled, read-only or write-enabled access to a private local Yaps Markdown vault, enabling AI clients to search, read, and manage notes securely.MIT
- AlicenseAqualityDmaintenanceProvides read-only access to a local Obsidian vault with zero-trust security, enabling note reading, listing, and text search via Claude.37,721 npmMIT