@devheerim/notion-mcp-server
Notion 공식 API를 래핑한 MCP(Model Context Protocol) 서버입니다. 기본 제공되는 Notion MCP를 대체하며, 데이터베이스 쿼리 기능이 훨씬 더 강력합니다.
주요 기능
query_database: 필터, 정렬, 페이지네이션을 완벽하게 지원하는 데이터베이스 쿼리- 프로퍼티 기반 필터링: 복잡한 AND/OR 조건으로 정밀한 데이터 조회
- 전체 12개 도구: 페이지 CRUD, 댓글, 사용자 관리 등 포괄적인 기능
설치
npm install -g @devheerim/notion-mcp-server
설정
1. Notion Integration 토큰 발급
- Notion Integrations에서 새 통합 생성
- 생성된 Internal Integration Secret 복사 (
ntn_으로 시작)
2. Notion에서 Integration 연결
접근할 페이지/데이터베이스마다:
- 우측 상단 ... > 연결 클릭
- 생성한 Integration 선택
3. MCP 클라이언트에 등록
Claude Desktop / Claude Code
claude_desktop_config.json 또는 ~/.claude/settings.json에 추가:
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "@devheerim/notion-mcp-server"],
"env": {
"NOTION_API_KEY": "ntn_your_token_here"
}
}
}
}
직접 실행
NOTION_API_KEY=ntn_your_token_here notion-mcp-server
도구 목록
| 도구 | 설명 |
|---|---|
query_database | 데이터베이스를 필터, 정렬, 페이지네이션으로 쿼리 |
fetch_page | 페이지 상세 정보 및 블록 콘텐츠 조회 |
search | 워크스페이스 전체 검색 |
create_page | 새 페이지 생성 |
update_page | 기존 페이지 수정 |
create_database | 새 데이터베이스 생성 |
update_database | 데이터베이스 스키마 및 속성 수정 |
create_comment | 페이지에 댓글 추가 |
get_comments | 페이지의 모든 댓글 조회 |
get_users | 워크스페이스 사용자 조회 |
move_pages | 페이지를 다른 위치로 이동 |
duplicate_page | 기존 페이지 복제 |
사용 예시
상태가 "완료"인 작업 조회
query_database:
database_id: "12345678901234567890123456789012"
filter:
property: "Status"
select:
equals: "완료"
복합 필터 + 정렬
query_database:
database_id: "12345678901234567890123456789012"
filter:
and:
- property: "Priority"
select:
equals: "높음"
- property: "Status"
select:
equals: "미완료"
sorts:
- property: "Created"
direction: "descending"
날짜 기반 필터 + 페이지네이션
query_database:
database_id: "12345678901234567890123456789012"
filter:
property: "Due Date"
date:
before: "2026-02-22"
page_size: 25
기술 스택
- TypeScript + Node.js
- @modelcontextprotocol/sdk - MCP 서버 프레임워크
- @notionhq/client - Notion 공식 API 클라이언트
- Zod - 입력 스키마 검증
라이선스
MIT