Notion Task Remote MCP Worker

ChatGPT·Claude가 구조화한 할 일을 Notion 데이터 소스에 저장하는 Cloudflare Worker입니다. /mcp에서 Streamable HTTP MCP를 제공하며 자연어 파싱은 하지 않습니다. Cloudflare가 새 상태 없는 서버에 권장하는 createMcpHandler()와 MCP SDK v2를 사용하고, Notion API 2026-03-11의 data_source_id 부모로 페이지를 생성합니다.

보안 경고: 현재 코드는 로컬 MVP 검증용이며 인증이 없습니다. 인터넷에 공개 배포하면 URL을 아는 누구나 Notion에 항목을 만들 수 있습니다. OAuth를 적용하기 전에는 운영용으로 배포하거나 ChatGPT/Claude에 연결하지 마세요. URL 난독화는 인증이 아닙니다.

구조

src/index.ts                 Worker 라우팅과 MCP 핸들러
src/mcp/tools.ts             create_task 도구 정의
src/validation/task.ts       입력 스키마와 검증
src/notion/client.ts         Workers 호환 Notion HTTP 클라이언트
src/notion/createTask.ts     속성·본문 매핑
src/notion/schema.ts         속성명과 API 버전 상수
src/notion/errors.ts         안전한 사용자 오류 변환
test/                        실제 API를 호출하지 않는 단위 테스트

Related MCP server: Notion MCP Server

Notion 준비

1. Notion에서 새 데이터베이스를 만들고 다음 속성을 정확히 추가합니다.

   이름	타입	값/설명
   이름	Title	기본 제목
   프로젝트	Select	필요한 옵션을 추가하거나 API 생성 허용
   분류	Select	프로젝트 옵션
   마감일	Date	선택
   상태	Status	현재 연결된 데이터 소스의 Not started 옵션 사용 (할 일로 이름을 바꾸면 src/notion/schema.ts도 변경)
   알림발송	Checkbox	기본 false

2. Notion Integrations에서 내부 Integration을 만들고 Read content, Insert content 권한을 부여합니다.

3. 데이터베이스 우측 상단 … → Connections에서 Integration을 연결합니다. 연결하지 않으면 API가 해당 데이터 소스를 볼 수 없습니다.

4. 데이터베이스의 Manage data sources에서 대상 데이터 소스를 열고 URL을 확인합니다. 최신 API에서는 데이터베이스 컨테이너 ID가 아니라 Data Source ID가 필요합니다. 확실하지 않으면 Notion의 Retrieve a database 응답에 포함된 data_sources[].id를 사용하세요.

속성명을 바꾸려면 src/notion/schema.ts의 상수만 수정하면 됩니다.

로컬 실행과 테스트

npm install
cp .dev.vars.example .dev.vars
# .dev.vars에 실제 NOTION_TOKEN과 NOTION_DATA_SOURCE_ID 입력
npm run typecheck
npm test
npm run dev

기본 테스트는 mock client만 사용하므로 실제 Notion 데이터를 만들지 않습니다. 실제 연동 테스트는 wrangler dev 실행 후 아래 Inspector에서 직접 create_task를 호출하는 방식으로 명시적으로 수행합니다.

npx @modelcontextprotocol/inspector@latest

Inspector에서 transport를 Streamable HTTP로 선택하고 http://localhost:8787/mcp에 연결합니다. List Tools에서 create_task를 확인한 뒤 다음 입력으로 호출합니다.

{
  "title": "보고서 작성",
  "project": "사포리",
  "category": "프로젝트",
  "dueAt": "2026-08-11T23:59:00+09:00",
  "details": "중간심사 피드백을 반영하고 PDF로 제출"
}

Notion에서 여섯 속성과 paragraph 본문을 확인합니다. details나 dueAt을 빼고 다시 호출해 빈 본문·마감일이 생성되지 않는지도 확인합니다.

배포 및 Secret

아래 명령은 OAuth 적용을 마친 뒤에만 운영 환경에서 실행하세요.

npx wrangler secret put NOTION_TOKEN
npx wrangler secret put NOTION_DATA_SOURCE_ID
npm run deploy

배포 URL은 https://<worker-name>.<account-subdomain>.workers.dev/mcp이며 ChatGPT/Claude의 원격 MCP URL로 사용합니다. 상태 확인은 /health입니다. Secret과 .dev.vars는 Git에서 제외되며 로그에는 토큰, Authorization 헤더, 요청 본문을 남기지 않습니다.

운영 인증 적용

MCP 원격 인증은 OAuth 2.1 흐름이어야 합니다. Cloudflare의 @cloudflare/workers-oauth-provider와 다음 중 하나를 구성한 뒤 /mcp를 보호하세요.

• Cloudflare Access for SaaS (조직 SSO/일회용 PIN 및 Access 정책)

• GitHub, Google, Auth0, Stytch, WorkOS 같은 외부 IdP

Cloudflare의 Remote MCP Authorization 문서와 Access for SaaS 예제를 따라 /authorize, /token, /register를 제공하고, 쓰기 도구 전용 scope를 검사해야 합니다. IdP 선택, 허용 사용자 정책, OAuth client 설정은 배포 계정의 외부 구성이므로 이 MVP에는 임의의 로그인 공급자를 넣지 않았습니다.

오류 처리와 제한

• 제목과 본문은 Notion rich-text 한도인 2,000자로 제한합니다.

• dueAt은 시간대(Z 또는 +09:00)가 포함된 ISO 8601만 받습니다.

• 권한, Data Source ID, 속성 스키마, 요청 제한, 일시 장애를 구분해 안전한 메시지를 반환합니다.

• Notion의 내부 응답 메시지나 Secret은 MCP 응답에 노출하지 않고, 로그에는 상태 코드·오류 코드·request ID만 남깁니다.

참고: Cloudflare Remote MCP, Notion Create a page, Notion request limits