Apple Notes MCP 서버

Name: Apple Notes MCP Server
Author: ailenshen

Apple Notes 기본 서식을 지원하며 Apple Notes를 읽고 씁니다.

apple-notes-mcp MCP server

대부분의 Apple Notes MCP 서버는 일반 텍스트만 작성할 수 있습니다. 이 서버는 기본 서식이 적용된 노트를 생성합니다. 제목, 헤딩, 굵게, 목록 등이 일반 텍스트가 아닌 실제 Apple Notes 스타일로 렌더링됩니다. 이는 Notes.app의 내장 Markdown 가져오기 기능을 활용하여 구현되었습니다.

요구 사항: macOS 26 (Tahoe) 이상, Node.js 24 이상

설정

1. MCP 클라이언트에 추가

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집하세요:

{
  "mcpServers": {
    "apple-notes": {
      "command": "npx",
      "args": ["-y", "@ailenshen/apple-notes-mcp@latest"]
    }
  }
}

Claude Code — 터미널에서 실행하세요:

claude mcp add apple-notes -- npx -y @ailenshen/apple-notes-mcp@latest

2. 권한 부여

기본 서식을 지원하기 위해 이 서버는 Notes.app의 내장 Markdown 가져오기 기능을 사용합니다. 즉, .md 파일을 Notes.app으로 열고 가져오기 대화 상자를 자동으로 확인합니다. 이를 위해서는 node에 대해 두 가지 macOS 권한이 필요합니다:

권한	활성화 위치	이유
전체 디스크 접근 권한	시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근 권한 > `node` 활성화	목록 및 검색을 위해 Notes 데이터베이스 읽기
손쉬운 사용	시스템 설정 > 개인정보 보호 및 보안 > 손쉬운 사용 > `node` 활성화	노트 생성 시 가져오기 대화 상자 자동 확인

처음 사용할 때 macOS가 승인을 요청하면 '허용'을 클릭하세요. 메시지를 놓쳤다면 위의 설정으로 이동하여 node를 수동으로 켜주세요. 권한을 부여한 후 MCP 클라이언트를 다시 시작하세요.

권한이 누락된 경우, 서버가 정확히 어떤 권한이 필요한지, 어떻게 해결해야 하는지 알려줍니다.

3. 사용 시작

AI와 자연스럽게 대화하세요:

"Projects 폴더에 있는 내 모든 노트 나열해줘"
"내 노트에서 '회의 안건' 검색해줘"
"내 쇼핑 목록 노트 읽어줘"
"Work 폴더에 오늘의 할 일 항목이 포함된 노트 생성해줘"
"내 쇼핑 목록에 이 새로운 항목들을 업데이트해줘"
"'오래된 초안'이라는 이름의 노트 삭제해줘"

무엇을 할 수 있나요?

도구	설명
`list_notes`	노트 탐색, 폴더별 필터링 가능
`search_notes`	키워드로 노트 찾기
`get_note`	전체 내용을 Markdown으로 읽기
`create_note`	Markdown 작성 → 기본 서식이 적용된 노트 생성
`update_note`	폴더를 유지하면서 내용 교체
`delete_note`	최근 삭제된 항목으로 이동

Notes에서의 Markdown 지원

요소	작동 여부
헤딩, 굵게, 기울임꼴, 목록, `inline code`	예
블록 인용	내용은 유지되나 들여쓰기 스타일 없음
링크	텍스트는 유지되나 URL 손실
표, 각주	아니요

원격 액세스 (HTTP 모드)

휴대폰이나 다른 컴퓨터에서 Apple Notes에 액세스하고 싶으신가요?

npx @ailenshen/apple-notes-mcp@latest --http

이 명령은 내장된 비밀 키가 포함된 엔드포인트 URL을 출력합니다:

Endpoint: http://localhost:3100/mcp/a3f8b2c9e1d4...

원격 MCP 클라이언트를 이 URL로 지정하세요. 인터넷을 통해 액세스하려면 터널(ngrok, Cloudflare Tunnel 등)을 사용하여 HTTPS 뒤에 배치하세요.

플래그	기본값	설명
`--port <number>`	3100	포트 번호
`--secret <string>`	무작위	사용자 지정 URL 비밀 키

재부팅 후에도 계속 실행되도록 하려면 위키에서 LaunchAgent 예시를 확인하세요.

작동 원리

작업	방식	속도
목록 / 검색	SQLite (읽기 전용)	< 100ms
읽기	AppleScript → Markdown	~1초
생성	기본 Markdown 가져오기	~0.5초
업데이트	삭제 + 생성	~1.5초
삭제	AppleScript	~1초

읽기는 SQLite를 통해 Notes 데이터베이스를 직접 쿼리하므로 빠르고 안전합니다. 내용은 turndown을 통해 Apple의 HTML에서 Markdown으로 변환됩니다.
생성은 macOS의 기본 Markdown 가져오기(open -a Notes)를 사용하므로 서식이 기본적으로 유지됩니다. 생성 중에 Notes.app이 잠시(~0.5초) 나타납니다.
업데이트는 이전 노트를 삭제하고 새 노트를 생성하며, 원본 폴더를 자동으로 유지합니다.
삭제는 수동으로 삭제하는 것과 동일하게 노트를 '최근 삭제된 항목'으로 이동시킵니다.

알려진 제한 사항

부분 노트 편집(예: "이 단락만 수정해줘")은 지원되지 않습니다. update_note는 항상 전체 내용을 교체합니다. 이는 Notes가 콘텐츠를 노출하는 방식의 근본적인 제한입니다. AppleScript 인터페이스는 원본 Markdown이 아닌 HTML을 반환하므로, 현재로서는 깔끔한 읽기→편집→쓰기 왕복이 불가능합니다.
노트 생성 중 Notes.app이 잠시 나타납니다. Markdown 가져오기 흐름은 Notes.app에서 대화 상자를 자동으로 확인해야 하므로, 잠시 동안 앱이 포그라운드로 나타날 수 있습니다.

이러한 제한 사항은 Apple이 AppleScript에 Markdown 가져오기/내보내기를 추가하거나 공식 Notes API를 공개하면 해결될 것이며, 두 가지 모두 향후 macOS 릴리스를 위해 추적 중입니다.

비전

Apple Notes는 Apple 기기에서 개인 지식을 보관하기에 가장 자연스러운 곳입니다. 어디서나 동기화되고, 빠르며, 비공개적입니다. 하지만 API가 없는 폐쇄적인 환경입니다.

이 프로젝트는 Apple Notes를 AI를 위한 일류 데이터 소스로 만듭니다. 장기적인 목표는 Mac, 휴대폰, 웹 등 어디에서 AI와 대화하든 Apple Notes에 항상 액세스하고, 읽고, 쓸 수 있도록 하는 것입니다.

라이선스

MIT

Apple Notes MCP Server