notion-local-ops-mcp

Notion AI를 로컬 파일, 셸 및 대체 로컬 에이전트와 함께 사용하세요.

📖 프로젝트 소개 (Notion 페이지)

제공 기능

• list_files

• search_files

• read_file

• replace_in_file

• write_file

• run_command

• delegate_task

• get_task

• cancel_task

delegate_task는 로컬 codex 및 claude CLI를 지원합니다.

요구 사항

• Python 3.11+

• cloudflared

• 사용자 지정 MCP 지원이 포함된 Notion 커스텀 에이전트

• 선택 사항: codex CLI

• 선택 사항: claude CLI

설치

git clone https://github.com/<your-account>/notion-local-ops-mcp.git
cd notion-local-ops-mcp

python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install -e .

구성

.env.example을 복사하고 최소한 다음을 설정하세요:

export NOTION_LOCAL_OPS_WORKSPACE_ROOT="/absolute/path/to/workspace"
export NOTION_LOCAL_OPS_AUTH_TOKEN="replace-me"

선택 사항:

export NOTION_LOCAL_OPS_CODEX_COMMAND="codex"
export NOTION_LOCAL_OPS_CLAUDE_COMMAND="claude"
export NOTION_LOCAL_OPS_COMMAND_TIMEOUT="30"
export NOTION_LOCAL_OPS_DELEGATE_TIMEOUT="1800"

시작

source .venv/bin/activate
notion-local-ops-mcp

로컬 엔드포인트:

http://127.0.0.1:8766/mcp

cloudflared로 노출

퀵 터널

cloudflared tunnel --url http://127.0.0.1:8766

생성된 HTTPS URL을 /mcp와 함께 사용하세요.

명명된 터널

cloudflared-example.yml을 편집한 후 다음을 실행하세요:

cloudflared tunnel --config ./cloudflared-example.yml run <your-tunnel-name>

Notion에 추가

다음 정보를 사용하세요:

• URL: https://<your-domain-or-tunnel>/mcp

• 인증 유형: Bearer

• 토큰: NOTION_LOCAL_OPS_AUTH_TOKEN 값

권장 에이전트 지침:

Use direct tools first: list_files, search_files, read_file, replace_in_file, write_file, run_command.
Use delegate_task only for complex multi-file work, long-running tasks, or when direct tools are insufficient.

환경 변수

도구 참고 사항

• list_files: 파일 및 디렉토리 목록 표시

• search_files: 파일 내 텍스트 검색

• read_file: 오프셋과 제한을 사용하여 텍스트 파일 읽기

• replace_in_file: 정확히 일치하는 텍스트 조각 하나를 교체

• write_file: 전체 파일 내용 쓰기

• run_command: 로컬 셸 명령 실행

• delegate_task: 로컬 codex 또는 claude로 작업 전송

• get_task: 작업 상태 및 출력 끝부분 읽기

• cancel_task: 위임된 작업 중지

확인

source .venv/bin/activate
pytest -q
python -m compileall src tests

문제 해결

Notion에서 연결할 수 없다고 표시되는 경우

• URL이 /mcp로 끝나는지 확인하세요

• 인증 유형이 Bearer인지 확인하세요

• 토큰이 NOTION_LOCAL_OPS_AUTH_TOKEN과 일치하는지 확인하세요

• cloudflared가 여전히 실행 중인지 확인하세요

SSE 경로가 로컬에서는 작동하지만 터널을 통해서는 작동하지 않는 경우

• 퀵 터널 대신 명명된 터널로 다시 시도하세요

• GET /mcp가 text/event-stream을 반환하는지 확인하세요

delegate_task가 실패하는 경우

• codex --help를 확인하세요

• claude --help를 확인하세요

• 필요한 경우 NOTION_LOCAL_OPS_CODEX_COMMAND 또는 NOTION_LOCAL_OPS_CLAUDE_COMMAND를 설정하세요