agent-notes-mcp

agent-notes-mcp is a local stdio MCP server for safely searching and editing personal Markdown notes from MCP clients such as Codex.

It uses ordinary full-text search across filenames, YAML frontmatter, and the Markdown body. No vector DB or embedding model is required.

Main Features

• Search, list, and read Markdown notes within the configured roots

• Create, append to, replace, and move notes within writable roots

• SHA-256-based conflict detection when replacing or moving notes

• Safe batch updates of explicitly marked Markdown blocks

• Arbitrary batch updates, update timestamp recording, and an activity log

• No delete operations and no network listening

See the security model for access boundaries and update guarantees.

Related MCP server: Notes — local markdown knowledge base

Requirements

• Python 3.14 or higher

• uv

Installation

To install from a local checkout:

uv tool install .

To install from the GitHub main branch:

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

For a specific commit or tag, append @<ref> to the end of the URL.

Configuration

Copy the example configuration and replace each path with a directory you manage.

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

read_roots allows searching and reading. write_roots allows searching, reading, and editing, and must be placed inside a readable root. Start with a narrow writable root, such as inbox or memos.

Registering with Codex

Register the installed command as a stdio MCP server.

[mcp_servers.agent_notes]
command = "agent_notes"

If using a source checkout, specify a config file explicitly.

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

First 5 Minutes

Open a new thread in Codex and start by asking it to do the following:

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

Codex can use MCP tools such as list_roots, search_notes, and read_note. When you want to try writing, ask it to create a new test Markdown file inside the narrow write_roots that your configuration allows.

For handing notes across multiple development repositories, see the example Codex project context and the example skill that you can copy and adapt. This workflow is optional; the server does not impose a particular note layout or format.

Safe Updates

Before replacing or moving an existing note, read it and specify the returned sha256 as expected_sha256. If the content has changed in the meantime, the server rejects the update rather than overwriting it.

To limit which parts of a note may be updated, wrap those parts in managed blocks.

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

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

update_managed_blocks updates only managed blocks whose structure could be verified. batch_update_notes validates every target update before it starts writing.

Development

uv sync --all-groups
uv run pytest

License

MIT

About Development

This project uses Codex as a development aid. The maintainer reviews content and makes all decisions before anything is released.