onenote-mcp

Claude가 OneNote 전자 필기장을 읽을 수 있게 해 주는 로컬 MCP 서버입니다. 전자 필기장에 붙여넣은 그림까지 포함해서 읽습니다.

OneNote 데스크톱 애플리케이션과 COM 인터페이스를 통해 통신합니다. Azure 앱 등록이나 테넌트 동의가 필요 없고, 어떤 데이터도 컴퓨터 밖으로 나가지 않습니다.

존재 이유

Microsoft 365 커넥터는 OneNote를 지원하지 않습니다. OneNote를 요청하면 mime type 'application/msonenote' is not allowed 오류와 함께 거부됩니다. 모든 Graph API 경로에는 Notes.ReadWrite.All 권한이 있는 Entra 앱 등록이 필요하며, 기업 테넌트에서는 이 등록이 IT 요청을 뜻합니다. 데스크톱 COM API에는 둘 다 필요하지 않습니다.

Related MCP server: notebooklm-claude-integration

할 수 있는 일

• 열려 있는 모든 전자 필기장을, 붙여넣은 스크린샷 안의 텍스트까지 포함하여, 검색합니다. OneNote 자체 인덱스가 OCR을 포함하기 때문입니다.

• 페이지를 텍스트로 읽고, 페이지에 있는 이미지 목록을 함께 반환합니다.

• 그 이미지들을 대화 기록에 알맞게 축소한 이미지로 반환합니다.

읽기 전용입니다. 어떤 것도 변경, 생성, 삭제할 수 없습니다.

요구 사항

• Windows, OneNote 데스크톱 애플리케이션이 설치되어 있어야 합니다. Microsoft Store에서 받은 OneNote 앱은 다른 프로그램이며 COM 인터페이스가 없습니다.

• Python 3.11 이상. 32비트/64비트 여부는 상관하지 않습니다.

설치

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e .

등록

이 폴더에 있는 .mcp.json이 이 프로젝트의 서버를 등록합니다. 어디서든 사용하려면:

claude mcp add onenote -s user -- C:\path\to\onenote_COM_mcp\.venv\Scripts\python.exe -m onenote_mcp.server

같은 명령은 Claude Desktop과 VS Code 확장에서도 작동합니다.

도구

get_page와 get_page_images은 의도적으로 분리되어 있습니다. 한 페이지에는 원본 크기의 스크린샷이 열두 장까지도 들어 있을 수 있는데, 페이지의 텍스트를 읽을 때 그 모든 이미지를 함께 대화로 끌어들여서는 안 되기 때문입니다.

OneNote가 이미지 안에서 인식한 텍스트가 필요하다면, get_page에 include_ocr 파라미터로 요청해 보세요. 이 텍스트는 이미지를 아예 가져오지 않고도 질문에 답을 하는 데 충분한 경우가 많습니다.

첫 번째 호출은 느립니다

서버는 첫 번째 도구 호출이 있을 때까지 OneNote를 연결하지 않습니다. 그 첫 호출에서는 OneNote가 닫혀 있으면 OneNote를 시작하기 때문에 시간이 걸릴 수 있습니다. 이후 호출은 빠릅니다. 10페이지짜리 섹션이면 약 2초 안에 읽힙니다.

개발

.venv\Scripts\python.exe -m pytest        # no OneNote needed
.venv\Scripts\python.exe tools\smoke.py   # live check, needs OneNote

com.py를 변경하기 전에 CLAUDE.md를 읽어 주세요. COM 인터페이스에는 원인을 찾는 데 하루가 걸리는 함정이 두 가지 있고, 그중 하나는 OneNote 프로세스를 죽입니다.