NotionMCP Light

NotionMCP Light는 Notion API를 사용하여 Markdown 파일과 Notion 페이지를 동기화하는 MCP(Model Context Protocol) 서버입니다.

개요

이 프로젝트는 Notion의 공식 Model Context Protocol (MCP) 서버가 가지고있는 비효율성 (Markdown을 블록 단위로 읽고 쓰고 LLM 토큰을 소비한다는 점)을 해결하기 위해 개발되었습니다. 토큰을 사용하지 않고 API를 통해 Markdown 파일과 Notion 페이지/데이터베이스를 직접 동기화할 수 있는 비공식 MCP 서버를 제공합니다.

기능

Markdown → Notion
- H1을 페이지 제목으로 인식
- Markdown의 내용을 Notion 페이지 또는 데이터베이스 페이지로 작성
- 데이터베이스 ID 지정 가능
- Notion API를 직접 사용(토큰 미사용)
Notion → Markdown
- 지정된 페이지 또는 데이터베이스의 페이지를 Markdown 형식으로 변환
- 제목을 H1로 출력
- 블록 구조를 Markdown으로 변환
- 파일에 저장
MCP 서버 지원
- Model Context Protocol(MCP) 준수
- Cursor 및 Cline과 같은 AI 도구에서 호출할 수 있는 엔드포인트 제공
- JSON-RPC over stdio 기반에서 작동

설치

종속성 설치

# uvがインストールされていない場合は先にインストール
# pip install uv

# 依存関係のインストール
uv sync

Notion API Token 설정

Notion Developers 에서 계정을 만들고 API 토큰을 가져옵니다.
환경 변수로 설정하거나 .env 파일을 작성하여 토큰을 설정합니다.

# .envファイルの例
NOTION_TOKEN=your_notion_api_token

사용법

MCP 서버 시작

uv를 사용하는 경우(권장)

uv run python -m src.main

또는 토큰을 직접 지정하는 경우:

uv run python -m src.main --token your_notion_api_token

일반 Python을 사용하는 경우

python -m src.main

또는 토큰을 직접 지정하는 경우:

python -m src.main --token your_notion_api_token

Cline/Cursor에서 설정

Cline/Cursor와 같은 AI 도구에서 NotionMCP Light를 사용하려면 mcp_settings.json 파일에 다음과 같은 설정을 추가합니다.

"notion-mcp-light": {
  "command": "uv",
  "args": [
    "run",
    "--directory",
    "/path/to/notion-mcp-light",
    "python",
    "-m",
    "src.main"
  ],
  "env": {
    "NOTION_TOKEN": "your_notion_api_token"
  },
  "disabled": false,
  "alwaysAllow": []
}

/path/to/notion-mcp-light 를 NotionMCP Light 설치 디렉토리로 바꿉니다.

MCP 도구 사용

NotionMCP Light는 다음 MCP 도구를 제공합니다.

uploadMarkdown

Markdown 파일을 업로드하고 Notion 페이지로 만듭니다.

{
  "jsonrpc": "2.0",
  "method": "uploadMarkdown",
  "params": {
    "filepath": "path/to/markdown.md",
    "database_id": "optional_database_id",
    "page_id": "optional_parent_page_id"
  },
  "id": 1
}

downloadMarkdown

Notion 페이지를 다운로드하여 Markdown 파일로 저장합니다.

{
  "jsonrpc": "2.0",
  "method": "downloadMarkdown",
  "params": {
    "page_id": "notion_page_id",
    "output_path": "path/to/output.md"
  },
  "id": 2
}

라이센스

이 프로젝트는 MIT 라이센스하에 게시됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.