agent-notes-mcp

agent-notes-mcp는 Codex 등의 MCP 클라이언트에서 개인용 Markdown 노트를 안전하게 검색·편집하기 위한 로컬 stdio MCP 서버입니다.

파일 이름, YAML frontmatter, Markdown 본문의 일반적인 전체 텍스트 검색을 사용합니다. 벡터 DB나 임베딩 모델은 필요 없습니다.

주요 기능

• 설정한 루트 내의 Markdown 노트 검색·목록·읽기

• 쓰기 가능한 루트 내에서 노트 생성, 추가, 교체, 이동

• 교체·이동 시 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는 검색·읽기·편집을 허용하며, 읽기 가능한 루트의 안쪽에 있어야 합니다. 처음에는 inbox나 memos처럼 좁은 쓰기 루트부터 시작하세요.

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를 개발 지원에 이용하고 있습니다. 공개 전 내용 확인과 판단은 유지보수 담당자가 수행합니다.