@devheerim/notion-mcp-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 devheerim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# @devheerim/notion-mcp-server
+
+[![npm version](https://img.shields.io/npm/v/@devheerim/notion-mcp-server.svg)](https://www.npmjs.com/package/@devheerim/notion-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Notion 공식 API를 래핑한 MCP(Model Context Protocol) 서버입니다. 기본 제공되는 Notion MCP를 대체하며, **데이터베이스 쿼리 기능이 훨씬 더 강력합니다.**
+
+## 주요 기능
+
+- **`query_database`**: 필터, 정렬, 페이지네이션을 완벽하게 지원하는 데이터베이스 쿼리
+- **프로퍼티 기반 필터링**: 복잡한 AND/OR 조건으로 정밀한 데이터 조회
+- **전체 12개 도구**: 페이지 CRUD, 댓글, 사용자 관리 등 포괄적인 기능
+
+## 설치
+
+```bash
+npm install -g @devheerim/notion-mcp-server
+```
+
+## 설정
+
+### 1. Notion Integration 토큰 발급
+
+1. [Notion Integrations](https://www.notion.so/my-integrations)에서 새 통합 생성
+2. 생성된 **Internal Integration Secret** 복사 (`ntn_` 으로 시작)
+
+### 2. Notion에서 Integration 연결
+
+접근할 페이지/데이터베이스마다:
+1. 우측 상단 **...** > **연결** 클릭
+2. 생성한 Integration 선택
+
+### 3. MCP 클라이언트에 등록
+
+#### Claude Desktop / Claude Code
+
+`claude_desktop_config.json` 또는 `~/.claude/settings.json`에 추가:
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@devheerim/notion-mcp-server"],
+      "env": {
+        "NOTION_API_KEY": "ntn_your_token_here"
+      }
+    }
+  }
+}
+```
+
+#### 직접 실행
+
+```bash
+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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+// Import all tool registrations
+import { register as registerQueryDatabase } from './tools/query-database.js';
+import { register as registerFetchPage } from './tools/fetch-page.js';
+import { register as registerSearch } from './tools/search.js';
+import { register as registerCreatePage } from './tools/create-page.js';
+import { register as registerUpdatePage } from './tools/update-page.js';
+import { register as registerCreateDatabase } from './tools/create-database.js';
+import { register as registerCreateComment } from './tools/create-comment.js';
+import { register as registerGetComments } from './tools/get-comments.js';
+import { register as registerGetUsers } from './tools/get-users.js';
+import { register as registerMovePages } from './tools/move-pages.js';
+import { register as registerDuplicatePage } from './tools/duplicate-page.js';
+import { register as registerUpdateDatabase } from './tools/update-database.js';
+const server = new McpServer({
+    name: 'notion-mcp-server',
+    version: '1.0.0',
+});
+// Register all tools
+registerQueryDatabase(server);
+registerFetchPage(server);
+registerSearch(server);
+registerCreatePage(server);
+registerUpdatePage(server);
+registerCreateDatabase(server);
+registerCreateComment(server);
+registerGetComments(server);
+registerGetUsers(server);
+registerMovePages(server);
+registerDuplicatePage(server);
+registerUpdateDatabase(server);
+// Start server with stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/notion-client.d.ts

@@ -0,0 +1,4 @@
+import { Client } from '@notionhq/client';
+export declare function getNotionClient(): Client;
+export declare function parseNotionId(input: string): string;
+export declare function formatApiError(error: unknown): string;

package/dist/notion-client.js

@@ -0,0 +1,78 @@
+import { Client } from '@notionhq/client';
+let notionClient = null;
+export function getNotionClient() {
+    if (!notionClient) {
+        const apiKey = process.env.NOTION_API_KEY;
+        if (!apiKey) {
+            throw new Error('NOTION_API_KEY environment variable is required');
+        }
+        notionClient = new Client({ auth: apiKey });
+    }
+    return notionClient;
+}
+export function parseNotionId(input) {
+    if (!input)
+        return input;
+    let cleaned = input.trim();
+    // Strip query params
+    const qIndex = cleaned.indexOf('?');
+    if (qIndex !== -1) {
+        cleaned = cleaned.slice(0, qIndex);
+    }
+    // Strip hash fragments
+    const hashIndex = cleaned.indexOf('#');
+    if (hashIndex !== -1) {
+        cleaned = cleaned.slice(0, hashIndex);
+    }
+    // Handle full Notion URLs:
+    // https://www.notion.so/workspace/Page-Title-abc123def456...
+    // https://notion.so/abc123def456...
+    // https://www.notion.so/abc123def456...
+    const urlPattern = /notion\.so\/(?:[^/]+\/)*([a-f0-9]{32}|[a-f0-9-]{36})\s*$/i;
+    const urlMatch = cleaned.match(urlPattern);
+    if (urlMatch) {
+        cleaned = urlMatch[1];
+    }
+    // Also handle the case where the ID is embedded at the end of a slug with dashes:
+    // e.g. "Page-Title-abc123def456" -> last 32 hex chars
+    const slugPattern = /[^a-f0-9]([a-f0-9]{32})$/i;
+    const slugMatch = cleaned.match(slugPattern);
+    if (slugMatch) {
+        cleaned = slugMatch[1];
+    }
+    // Strip dashes from UUID format: 12345678-90ab-cdef-1234-567890abcdef
+    const uuidWithDashes = /^([a-f0-9]{8})-([a-f0-9]{4})-([a-f0-9]{4})-([a-f0-9]{4})-([a-f0-9]{12})$/i;
+    if (uuidWithDashes.test(cleaned)) {
+        return cleaned.replace(/-/g, '');
+    }
+    // Already a 32-char hex string (UUID without dashes)
+    const uuidNoDashes = /^[a-f0-9]{32}$/i;
+    if (uuidNoDashes.test(cleaned)) {
+        return cleaned;
+    }
+    // Return as-is if we couldn't parse it (let Notion API produce the error)
+    return cleaned;
+}
+export function formatApiError(error) {
+    if (error && typeof error === 'object') {
+        const err = error;
+        // @notionhq/client throws APIResponseError with status, code, message
+        const status = err['status'];
+        const code = err['code'];
+        const message = err['message'];
+        if (status !== undefined && message) {
+            if (code) {
+                return `Notion API Error (${status}): [${code}] ${message}`;
+            }
+            return `Notion API Error (${status}): ${message}`;
+        }
+        if (message) {
+            return `Notion API Error: ${message}`;
+        }
+        // Fallback for generic Error instances
+        if (error instanceof Error) {
+            return `Error: ${error.message}`;
+        }
+    }
+    return `Unknown error: ${String(error)}`;
+}

package/dist/tools/create-comment.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/create-comment.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+export function register(server) {
+    server.tool('create_comment', '페이지에 댓글을 추가합니다.', {
+        page_id: z.string().describe('댓글을 추가할 페이지 ID 또는 URL'),
+        text: z.string().describe('댓글 내용 (plain text)'),
+        discussion_id: z
+            .string()
+            .optional()
+            .describe('기존 토론에 답글 달기 위한 discussion ID (선택)'),
+    }, async ({ page_id, text, discussion_id }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedPageId = parseNotionId(page_id);
+            const rich_text = [
+                {
+                    type: 'text',
+                    text: { content: text },
+                },
+            ];
+            let response;
+            if (discussion_id) {
+                response = await notion.comments.create({
+                    discussion_id,
+                    rich_text,
+                });
+            }
+            else {
+                response = await notion.comments.create({
+                    parent: { page_id: parsedPageId },
+                    rich_text,
+                });
+            }
+            const lines = [
+                `## 댓글 추가 완료`,
+                `- 댓글 ID: ${response.id}`,
+                `- 페이지 ID: ${parsedPageId}`,
+                `- 내용: ${text}`,
+                `- 생성 시간: ${response.created_time ?? ''}`,
+            ];
+            if (discussion_id)
+                lines.push(`- 토론 ID: ${discussion_id}`);
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/create-database.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/create-database.js

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+export function register(server) {
+    server.tool('create_database', '새 데이터베이스를 생성합니다.', {
+        parent_page_id: z.string().describe('부모 페이지 ID 또는 URL'),
+        title: z.string().describe('데이터베이스 제목'),
+        properties: z
+            .record(z.any())
+            .describe('프로퍼티 스키마 정의. 예: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name":"Todo","color":"red"}]}}}'),
+    }, async ({ parent_page_id, title, properties }) => {
+        try {
+            const notion = getNotionClient();
+            const parentId = parseNotionId(parent_page_id);
+            const response = await notion.databases.create({
+                parent: { type: 'page_id', page_id: parentId },
+                title: [
+                    {
+                        type: 'text',
+                        text: { content: title },
+                    },
+                ],
+                properties: properties,
+            });
+            const url = response.url ?? '';
+            const lines = [
+                `## 데이터베이스 생성 완료`,
+                `- ID: ${response.id}`,
+                `- 제목: ${title}`,
+            ];
+            if (url)
+                lines.push(`- URL: ${url}`);
+            lines.push(`- 프로퍼티 수: ${Object.keys(response.properties ?? {}).length}`);
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/create-page.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/create-page.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+import { formatProperties } from '../utils/format-properties.js';
+export function register(server) {
+    server.tool('create_page', '새 페이지를 생성합니다. 데이터베이스 내 항목 또는 독립 페이지 생성 가능.', {
+        parent_type: z
+            .enum(['database_id', 'page_id'])
+            .describe('부모 타입: "database_id" (DB 항목) 또는 "page_id" (하위 페이지)'),
+        parent_id: z.string().describe('부모 DB 또는 페이지의 ID / Notion URL'),
+        properties: z
+            .record(z.any())
+            .describe('페이지 프로퍼티 객체. 예시:\n' +
+            '  title: {"Name": {"title": [{"text": {"content": "제목"}}]}}\n' +
+            '  select: {"Status": {"select": {"name": "Done"}}}\n' +
+            '  multi_select: {"Tags": {"multi_select": [{"name": "A"}, {"name": "B"}]}}\n' +
+            '  date: {"Due": {"date": {"start": "2024-01-01"}}}\n' +
+            '  number: {"Count": {"number": 42}}\n' +
+            '  checkbox: {"Done": {"checkbox": true}}\n' +
+            '  url: {"Link": {"url": "https://example.com"}}'),
+        children: z
+            .array(z.record(z.any()))
+            .optional()
+            .describe('페이지 콘텐츠 블록 배열 (선택)'),
+    }, async ({ parent_type, parent_id, properties, children }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedParentId = parseNotionId(parent_id);
+            const createParams = {
+                parent: { [parent_type]: parsedParentId },
+                properties,
+            };
+            if (children && children.length > 0) {
+                createParams.children = children;
+            }
+            const response = await notion.pages.create(createParams);
+            const formattedProps = formatProperties(response.properties ?? {});
+            const lines = [
+                '## 페이지 생성 완료',
+                `- ID: ${response.id}`,
+                `- URL: ${response.url ?? ''}`,
+                `- 생성 시간: ${response.created_time ?? ''}`,
+                '',
+                '### 프로퍼티',
+            ];
+            for (const [key, value] of Object.entries(formattedProps)) {
+                if (value)
+                    lines.push(`- ${key}: ${value}`);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/duplicate-page.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;

package/dist/tools/duplicate-page.js

@@ -0,0 +1,185 @@
+import { z } from 'zod';
+import { getNotionClient, parseNotionId, formatApiError } from '../notion-client.js';
+// Block types that cannot be appended via the API
+const UNSUPPORTED_BLOCK_TYPES = new Set([
+    'synced_block',
+    'child_page',
+    'child_database',
+    'template',
+    'link_to_page',
+]);
+async function fetchBlocksRecursive(notion, blockId, depth) {
+    if (depth <= 0)
+        return [];
+    const blocks = [];
+    let cursor = undefined;
+    do {
+        const params = { block_id: blockId, page_size: 100 };
+        if (cursor)
+            params['start_cursor'] = cursor;
+        const response = await notion.blocks.children.list(params);
+        const results = response?.results ?? [];
+        blocks.push(...results);
+        cursor = response?.has_more ? response.next_cursor ?? undefined : undefined;
+    } while (cursor);
+    // Recursively fetch children up to the given depth
+    for (const block of blocks) {
+        if (block.has_children && depth > 1) {
+            block._children = await fetchBlocksRecursive(notion, block.id, depth - 1);
+        }
+    }
+    return blocks;
+}
+function stripBlockForCreate(block) {
+    const type = block.type;
+    if (UNSUPPORTED_BLOCK_TYPES.has(type))
+        return null;
+    const content = block[type];
+    if (!content)
+        return null;
+    const newBlock = { type, [type]: { ...content } };
+    // Attach children if available
+    if (block._children && block._children.length > 0) {
+        const childBlocks = [];
+        for (const child of block._children) {
+            const stripped = stripBlockForCreate(child);
+            if (stripped)
+                childBlocks.push(stripped);
+        }
+        if (childBlocks.length > 0) {
+            newBlock['children'] = childBlocks;
+        }
+    }
+    // Remove fields not allowed in create requests
+    delete newBlock[type].rich_text_annotations; // not a real field, just safety
+    delete newBlock['id'];
+    delete newBlock['created_time'];
+    delete newBlock['last_edited_time'];
+    delete newBlock['created_by'];
+    delete newBlock['last_edited_by'];
+    delete newBlock['parent'];
+    delete newBlock['object'];
+    delete newBlock['has_children'];
+    return newBlock;
+}
+function extractTitleFromProperties(properties) {
+    for (const prop of Object.values(properties)) {
+        if (prop?.type === 'title') {
+            const texts = prop.title ?? [];
+            return texts.map((t) => t?.plain_text ?? '').join('');
+        }
+    }
+    return '';
+}
+function overrideTitleInProperties(properties, newTitle) {
+    const updated = { ...properties };
+    for (const [key, prop] of Object.entries(updated)) {
+        if (prop?.type === 'title') {
+            updated[key] = {
+                ...prop,
+                title: [{ type: 'text', text: { content: newTitle } }],
+            };
+            break;
+        }
+    }
+    return updated;
+}
+function sanitizePropertiesForCreate(properties) {
+    const result = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        if (!prop || typeof prop !== 'object')
+            continue;
+        const type = prop.type;
+        // Only include writable property types
+        const writableTypes = new Set([
+            'title', 'rich_text', 'number', 'select', 'multi_select',
+            'date', 'people', 'files', 'checkbox', 'url', 'email',
+            'phone_number', 'relation', 'status',
+        ]);
+        if (!writableTypes.has(type))
+            continue;
+        result[key] = prop;
+    }
+    return result;
+}
+export function register(server) {
+    server.tool('duplicate_page', '페이지를 복제합니다.', {
+        page_id: z.string().describe('복제할 페이지 ID 또는 URL'),
+        new_title: z
+            .string()
+            .optional()
+            .describe('새 페이지 제목 (기본값: "원본제목 (복사)")'),
+    }, async ({ page_id, new_title }) => {
+        try {
+            const notion = getNotionClient();
+            const parsedId = parseNotionId(page_id);
+            // 1. Retrieve original page
+            const originalPage = await notion.pages.retrieve({ page_id: parsedId });
+            const originalProperties = originalPage.properties ?? {};
+            const originalParent = originalPage.parent ?? {};
+            // 2. Determine title
+            const originalTitle = extractTitleFromProperties(originalProperties);
+            const finalTitle = new_title ?? `${originalTitle || 'Untitled'} (복사)`;
+            // 3. Override title in properties
+            let newProperties = sanitizePropertiesForCreate(originalProperties);
+            newProperties = overrideTitleInProperties(newProperties, finalTitle);
+            // 4. Fetch blocks (recursive, depth 2)
+            const blocks = await fetchBlocksRecursive(notion, parsedId, 2);
+            const skippedTypes = [];
+            const childrenBlocks = [];
+            for (const block of blocks) {
+                if (UNSUPPORTED_BLOCK_TYPES.has(block.type)) {
+                    skippedTypes.push(block.type);
+                    continue;
+                }
+                const stripped = stripBlockForCreate(block);
+                if (stripped)
+                    childrenBlocks.push(stripped);
+            }
+            // 5. Create new page
+            const createParams = {
+                parent: originalParent,
+                properties: newProperties,
+            };
+            // Notion API allows max 100 children in create
+            if (childrenBlocks.length > 0) {
+                createParams['children'] = childrenBlocks.slice(0, 100);
+            }
+            const newPage = await notion.pages.create(createParams);
+            const newPageUrl = newPage.url ?? '';
+            // 6. Append remaining blocks in batches of 100
+            const remaining = childrenBlocks.slice(100);
+            let appendedExtra = 0;
+            for (let i = 0; i < remaining.length; i += 100) {
+                const batch = remaining.slice(i, i + 100);
+                await notion.blocks.children.append({
+                    block_id: newPage.id,
+                    children: batch,
+                });
+                appendedExtra += batch.length;
+            }
+            const lines = [
+                `## 페이지 복제 완료`,
+                `- 새 페이지 ID: ${newPage.id}`,
+                `- 새 페이지 제목: ${finalTitle}`,
+            ];
+            if (newPageUrl)
+                lines.push(`- URL: ${newPageUrl}`);
+            lines.push(`- 복사된 블록: ${childrenBlocks.length}개`);
+            if (appendedExtra > 0)
+                lines.push(`  (초기 100개 + 추가 ${appendedExtra}개 append)`);
+            if (skippedTypes.length > 0) {
+                lines.push(`- 건너뛴 블록 유형 (API 미지원): ${[...new Set(skippedTypes)].join(', ')}`);
+            }
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{ type: 'text', text: formatApiError(error) }],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/tools/fetch-page.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function register(server: McpServer): void;