agent-notes-mcp

agent-notes-mcp 是一个用于从 Codex 等 MCP 客户端安全地搜索和编辑个人 Markdown 笔记的本地 stdio MCP 服务器。

它使用文件名、YAML frontmatter 和 Markdown 正文的常规全文搜索。不需要向量数据库或嵌入模型。

主要功能

• 在配置好的 root 内搜索、列出和读取 Markdown 笔记

• 在可写 root 内创建、追加、替换和移动笔记

• 替换和移动时基于 SHA-256 的冲突检测

• 安全地批量更新明确标记的 Markdown 块

• 任意批量更新、记录更新时间、 activity log

• 不提供删除操作和网络监听

访问边界和更新时的保证请参阅 安全模型。

Related MCP server: Notes — local markdown knowledge base

环境要求

• Python 3.14 及以上

• uv

安装

从本地 checkout 安装时：

uv tool install .

从 GitHub 的 main 分支安装时：

uv tool install git+https://github.com/mitszo/agent-notes-mcp.git

如需指定某个提交或标签，请在 URL 末尾追加 @<ref>。

配置

复制配置示例，并将各项路径替换为自己管理的目录。

mkdir -p ~/.config/agent-notes-mcp
cp config.example.toml ~/.config/agent-notes-mcp/config.toml

read_roots 允许搜索和读取。write_roots 允许搜索、读取和编辑，并且必须放在可读的 root 内部。一开始请从 inbox 或 memos 这样范围较窄的可写 root 开始。

注册到 Codex

将安装好的命令注册为 stdio MCP 服务器。

[mcp_servers.agent_notes]
command = "agent_notes"

如果使用源码 checkout，请显式指定配置文件。

[mcp_servers.agent_notes]
command = "uv"
args = ["run", "agent_notes", "--config", "/absolute/path/to/config.toml"]

最初的 5 分钟

在 Codex 中打开新会话，首先按如下方式提出请求。

agent_notes で設定済みの root を確認し、ノートを検索できるか試してください。

Codex 可以使用 list_roots、search_notes、read_note 等 MCP 工具。尝试写入时，请让它在你配置所允许的窄 write_roots 内创建一个新的测试用 Markdown 文件。

如果要在多个开发仓库中使用笔记进行交接，请参阅 Codex 的项目上下文示例 和可复制并按需调整的 技能示例。这是可选做法，服务器不会强制规定笔记的布局或格式。

安全更新

在替换或移动现有笔记之前，先读取该笔记，并将返回的 sha256 指定为 expected_sha256。如果在此期间内容发生变化，服务器将拒绝更新，而不会覆盖。

如需限定笔记内允许更新的范围，请用管理块将其包围。

<!-- agent-notes:managed next-actions -->
## 次の行動

- 下書きを確認する
<!-- /agent-notes:managed next-actions -->

update_managed_blocks 只更新结构验证通过的管理块。batch_update_notes 会先验证所有目标更新，然后才开始写入。

开发

uv sync --all-groups
uv run pytest

许可证

MIT

关于开发

本项目使用 Codex 提供开发辅助。发布前的内容确认和判断均由维护者负责。