@atikk-co-jp/notion-mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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.ja.md

@@ -0,0 +1,203 @@
+# notion-mcp-server
+
+[English](./README.md) | 日本語
+
+Notion API用のMCP（Model Context Protocol）サーバー。AIアシスタントがNotionのページ、データベース、ブロックを操作できるようにします。
+
+> ⚠️ **注意**: これは初期リリースです。APIは変更される可能性があります。
+
+## 特徴
+
+- **ページ操作**: Notionページの作成、取得、更新
+- **データベースクエリ**: フィルターやソートを使ったデータベース検索
+- **ブロック操作**: ブロックの子要素の取得と追加
+- **検索**: ページとデータベースの横断検索
+- **コメント**: ページへのコメント追加
+
+## インストール
+
+```bash
+npm install @atikk-co-jp/notion-mcp-server
+# または
+pnpm add @atikk-co-jp/notion-mcp-server
+# または
+yarn add @atikk-co-jp/notion-mcp-server
+```
+
+## 使い方
+
+### Claude Desktopで使用する
+
+Claude Desktopの設定ファイル（macOSの場合: `~/.config/claude/claude_desktop_config.json`）に追加:
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@atikk-co-jp/notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "your-notion-integration-token"
+      }
+    }
+  }
+}
+```
+
+### Claude Codeで使用する
+
+`.mcp.json`に追加:
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@atikk-co-jp/notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "your-notion-integration-token"
+      }
+    }
+  }
+}
+```
+
+## Notionトークンの取得方法
+
+1. [Notion Integrations](https://www.notion.so/my-integrations)にアクセス
+2. 「新しいインテグレーション」をクリック
+3. 名前を入力し、ワークスペースを選択
+4. 「内部インテグレーションシークレット」をコピー（`ntn_`で始まる）
+5. アクセスしたいページ/データベースをインテグレーションと共有
+
+## 利用可能なツール
+
+### retrieve-page
+
+ページIDでNotionページを取得します。
+
+```json
+{
+  "page_id": "ページのUUID"
+}
+```
+
+### create-page
+
+データベースに新しいページを作成します。
+
+```json
+{
+  "database_id": "データベースのUUID",
+  "properties": {
+    "Name": {
+      "title": [{ "text": { "content": "新しいページタイトル" } }]
+    },
+    "Status": {
+      "status": { "name": "進行中" }
+    }
+  }
+}
+```
+
+### update-page
+
+ページのプロパティを更新します。
+
+```json
+{
+  "page_id": "ページのUUID",
+  "properties": {
+    "Status": {
+      "status": { "name": "完了" }
+    }
+  }
+}
+```
+
+### query-database
+
+フィルターやソートを使ってデータベースをクエリします。
+
+```json
+{
+  "database_id": "データベースのUUID",
+  "filter": {
+    "property": "Status",
+    "status": { "equals": "進行中" }
+  },
+  "sorts": [
+    { "property": "Created", "direction": "descending" }
+  ]
+}
+```
+
+### search
+
+すべてのページとデータベースを横断検索します。
+
+```json
+{
+  "query": "検索キーワード",
+  "filter": { "value": "page", "property": "object" }
+}
+```
+
+### get-block-children
+
+ページまたはブロックの子ブロックを取得します。
+
+```json
+{
+  "block_id": "ページまたはブロックのUUID"
+}
+```
+
+### append-block-children
+
+ページまたはブロックに新しいブロックを追加します。
+
+```json
+{
+  "block_id": "ページまたはブロックのUUID",
+  "children": [
+    {
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [{ "text": { "content": "新しい段落" } }]
+      }
+    }
+  ]
+}
+```
+
+### create-comment
+
+ページにコメントを追加します。
+
+```json
+{
+  "page_id": "ページのUUID",
+  "rich_text": [{ "type": "text", "text": { "content": "これはコメントです" } }]
+}
+```
+
+## 開発
+
+```bash
+# 依存関係のインストール
+pnpm install
+
+# 開発モードで実行
+pnpm dev
+
+# 本番用ビルド
+pnpm build
+
+# 型チェック
+pnpm typecheck
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,203 @@
+# notion-mcp-server
+
+English | [日本語](./README.ja.md)
+
+MCP (Model Context Protocol) server for Notion API. Enables AI assistants to interact with Notion pages, databases, and blocks.
+
+> ⚠️ **Note**: This is an early release. API may change.
+
+## Features
+
+- **Page Operations**: Create, retrieve, and update Notion pages
+- **Database Queries**: Query databases with filters and sorts
+- **Block Operations**: Get and append block children
+- **Search**: Search across pages and databases
+- **Comments**: Add comments to pages
+
+## Installation
+
+```bash
+npm install @atikk-co-jp/notion-mcp-server
+# or
+pnpm add @atikk-co-jp/notion-mcp-server
+# or
+yarn add @atikk-co-jp/notion-mcp-server
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on macOS):
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@atikk-co-jp/notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "your-notion-integration-token"
+      }
+    }
+  }
+}
+```
+
+### With Claude Code
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "notion": {
+      "command": "npx",
+      "args": ["-y", "@atikk-co-jp/notion-mcp-server"],
+      "env": {
+        "NOTION_TOKEN": "your-notion-integration-token"
+      }
+    }
+  }
+}
+```
+
+## Getting a Notion Token
+
+1. Go to [Notion Integrations](https://www.notion.so/my-integrations)
+2. Click "New integration"
+3. Give it a name and select the workspace
+4. Copy the "Internal Integration Token" (starts with `ntn_`)
+5. Share the pages/databases you want to access with your integration
+
+## Available Tools
+
+### retrieve-page
+
+Retrieve a Notion page by its ID.
+
+```json
+{
+  "page_id": "page-uuid-here"
+}
+```
+
+### create-page
+
+Create a new page in a database.
+
+```json
+{
+  "database_id": "database-uuid-here",
+  "properties": {
+    "Name": {
+      "title": [{ "text": { "content": "New Page Title" } }]
+    },
+    "Status": {
+      "status": { "name": "In Progress" }
+    }
+  }
+}
+```
+
+### update-page
+
+Update a page's properties.
+
+```json
+{
+  "page_id": "page-uuid-here",
+  "properties": {
+    "Status": {
+      "status": { "name": "Done" }
+    }
+  }
+}
+```
+
+### query-database
+
+Query a database with optional filters and sorts.
+
+```json
+{
+  "database_id": "database-uuid-here",
+  "filter": {
+    "property": "Status",
+    "status": { "equals": "In Progress" }
+  },
+  "sorts": [
+    { "property": "Created", "direction": "descending" }
+  ]
+}
+```
+
+### search
+
+Search across all pages and databases.
+
+```json
+{
+  "query": "search term",
+  "filter": { "value": "page", "property": "object" }
+}
+```
+
+### get-block-children
+
+Get the child blocks of a page or block.
+
+```json
+{
+  "block_id": "page-or-block-uuid-here"
+}
+```
+
+### append-block-children
+
+Append new blocks to a page or block.
+
+```json
+{
+  "block_id": "page-or-block-uuid-here",
+  "children": [
+    {
+      "type": "paragraph",
+      "paragraph": {
+        "rich_text": [{ "text": { "content": "New paragraph" } }]
+      }
+    }
+  ]
+}
+```
+
+### create-comment
+
+Add a comment to a page.
+
+```json
+{
+  "page_id": "page-uuid-here",
+  "rich_text": [{ "type": "text", "text": { "content": "This is a comment" } }]
+}
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run in development mode
+pnpm dev
+
+# Build for production
+pnpm build
+
+# Type check
+pnpm typecheck
+```
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/bin/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":""}

package/dist/bin/cli.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { startServer } from "../src/server.js";
+async function main() {
+    // Validate environment
+    if (!process.env.NOTION_TOKEN) {
+        console.error("Error: NOTION_TOKEN environment variable is required.");
+        console.error("");
+        console.error("To fix this:");
+        console.error("1. Create a Notion integration at https://www.notion.so/my-integrations");
+        console.error("2. Copy the Internal Integration Token");
+        console.error("3. Set it as NOTION_TOKEN environment variable");
+        console.error("");
+        console.error("Example:");
+        console.error('  NOTION_TOKEN="ntn_xxx..." npx notion-mcp-server');
+        process.exit(1);
+    }
+    try {
+        await startServer();
+    }
+    catch (error) {
+        console.error("Failed to start server:", error);
+        process.exit(1);
+    }
+}
+main();

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+export { createNotionClient, type NotionClient } from "./notion-client.js";
+export * from "./schemas/index.js";
+export { startServer } from "./server.js";
+export { registerAllTools, registerAppendBlockChildren, registerCreateComment, registerCreatePage, registerGetBlockChildren, registerQueryDatabase, registerRetrievePage, registerSearch, registerUpdatePage, } from "./tools/index.js";
+export type { McpResponse, McpTextContent } from "./utils/index.js";
+export { formatResponse, formatSuccessMessage, handleError } from "./utils/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAE3E,cAAc,oBAAoB,CAAC;AACnC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,qBAAqB,EACrB,oBAAoB,EACpB,cAAc,EACd,kBAAkB,GACnB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEpE,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/src/index.js

@@ -0,0 +1,9 @@
+// Main exports
+export { createNotionClient } from "./notion-client.js";
+// Schemas
+export * from "./schemas/index.js";
+export { startServer } from "./server.js";
+// Tool registration
+export { registerAllTools, registerAppendBlockChildren, registerCreateComment, registerCreatePage, registerGetBlockChildren, registerQueryDatabase, registerRetrievePage, registerSearch, registerUpdatePage, } from "./tools/index.js";
+// Utils
+export { formatResponse, formatSuccessMessage, handleError } from "./utils/index.js";

package/dist/src/notion-client.d.ts

@@ -0,0 +1,82 @@
+export interface NotionClientOptions {
+    token: string;
+}
+export interface NotionRequestOptions {
+    method?: "GET" | "POST" | "PATCH" | "DELETE";
+    body?: unknown;
+    query?: Record<string, string | number | undefined>;
+}
+export interface NotionError {
+    object: "error";
+    status: number;
+    code: string;
+    message: string;
+}
+export declare class NotionClient {
+    private token;
+    constructor(options: NotionClientOptions);
+    private request;
+    pages: {
+        create: <T>(params: {
+            parent: {
+                database_id: string;
+            } | {
+                page_id: string;
+            };
+            properties: Record<string, unknown>;
+            children?: unknown[];
+            icon?: unknown;
+            cover?: unknown;
+        }) => Promise<T>;
+        retrieve: <T>(params: {
+            page_id: string;
+        }) => Promise<T>;
+        update: <T>(params: {
+            page_id: string;
+            properties?: Record<string, unknown>;
+            archived?: boolean;
+            icon?: unknown;
+            cover?: unknown;
+        }) => Promise<T>;
+    };
+    databases: {
+        query: <T>(params: {
+            database_id: string;
+            filter?: unknown;
+            sorts?: unknown[];
+            start_cursor?: string;
+            page_size?: number;
+        }) => Promise<T>;
+    };
+    blocks: {
+        children: {
+            list: <T>(params: {
+                block_id: string;
+                start_cursor?: string;
+                page_size?: number;
+            }) => Promise<T>;
+            append: <T>(params: {
+                block_id: string;
+                children: unknown[];
+                after?: string;
+            }) => Promise<T>;
+        };
+    };
+    comments: {
+        create: <T>(params: {
+            parent: {
+                page_id: string;
+            };
+            rich_text: unknown[];
+        }) => Promise<T>;
+    };
+    search: <T>(params?: {
+        query?: string;
+        filter?: unknown;
+        sort?: unknown;
+        start_cursor?: string;
+        page_size?: number;
+    }) => Promise<T>;
+}
+export declare function createNotionClient(): NotionClient;
+//# sourceMappingURL=notion-client.d.ts.map

package/dist/src/notion-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"notion-client.d.ts","sourceRoot":"","sources":["../../src/notion-client.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;IAC7C,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEV,OAAO,EAAE,mBAAmB;YAI1B,OAAO;IAwCrB,KAAK;iBACM,CAAC,UAAU;YAClB,MAAM,EAAE;gBAAE,WAAW,EAAE,MAAM,CAAA;aAAE,GAAG;gBAAE,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC;YACtD,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACpC,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;YACrB,IAAI,CAAC,EAAE,OAAO,CAAC;YACf,KAAK,CAAC,EAAE,OAAO,CAAC;SACjB,KAAG,OAAO,CAAC,CAAC,CAAC;mBAIH,CAAC,UAAU;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,KAAG,OAAO,CAAC,CAAC,CAAC;iBAI7C,CAAC,UAAU;YAClB,OAAO,EAAE,MAAM,CAAC;YAChB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;YACnB,IAAI,CAAC,EAAE,OAAO,CAAC;YACf,KAAK,CAAC,EAAE,OAAO,CAAC;SACjB,KAAG,OAAO,CAAC,CAAC,CAAC;MAId;IAGF,SAAS;gBACC,CAAC,UAAU;YACjB,WAAW,EAAE,MAAM,CAAC;YACpB,MAAM,CAAC,EAAE,OAAO,CAAC;YACjB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;YAClB,YAAY,CAAC,EAAE,MAAM,CAAC;YACtB,SAAS,CAAC,EAAE,MAAM,CAAC;SACpB,KAAG,OAAO,CAAC,CAAC,CAAC;MAId;IAGF,MAAM;;mBAEK,CAAC,UAAU;gBAChB,QAAQ,EAAE,MAAM,CAAC;gBACjB,YAAY,CAAC,EAAE,MAAM,CAAC;gBACtB,SAAS,CAAC,EAAE,MAAM,CAAC;aACpB,KAAG,OAAO,CAAC,CAAC,CAAC;qBAOL,CAAC,UAAU;gBAClB,QAAQ,EAAE,MAAM,CAAC;gBACjB,QAAQ,EAAE,OAAO,EAAE,CAAC;gBACpB,KAAK,CAAC,EAAE,MAAM,CAAC;aAChB,KAAG,OAAO,CAAC,CAAC,CAAC;;MAKhB;IAGF,QAAQ;iBACG,CAAC,UAAU;YAAE,MAAM,EAAE;gBAAE,OAAO,EAAE,MAAM,CAAA;aAAE,CAAC;YAAC,SAAS,EAAE,OAAO,EAAE,CAAA;SAAE,KAAG,OAAO,CAAC,CAAC,CAAC;MAGtF;IAGF,MAAM,GAAI,CAAC,EAAE,SAAS;QACpB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,KAAG,OAAO,CAAC,CAAC,CAAC,CAEZ;CACH;AAED,wBAAgB,kBAAkB,IAAI,YAAY,CASjD"}

package/dist/src/notion-client.js

@@ -0,0 +1,93 @@
+const NOTION_API_BASE = "https://api.notion.com/v1";
+const NOTION_VERSION = "2022-06-28";
+export class NotionClient {
+    token;
+    constructor(options) {
+        this.token = options.token;
+    }
+    async request(endpoint, options = {}) {
+        const { method = "GET", body, query } = options;
+        let url = `${NOTION_API_BASE}${endpoint}`;
+        if (query) {
+            const params = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined) {
+                    params.set(key, String(value));
+                }
+            }
+            const queryString = params.toString();
+            if (queryString) {
+                url += `?${queryString}`;
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.token}`,
+            "Notion-Version": NOTION_VERSION,
+            "Content-Type": "application/json",
+        };
+        const response = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await response.json();
+        if (!response.ok) {
+            const error = data;
+            throw new Error(`Notion API error: ${error.code} - ${error.message}`);
+        }
+        return data;
+    }
+    // Pages
+    pages = {
+        create: (params) => {
+            return this.request("/pages", { method: "POST", body: params });
+        },
+        retrieve: (params) => {
+            return this.request(`/pages/${params.page_id}`);
+        },
+        update: (params) => {
+            const { page_id, ...body } = params;
+            return this.request(`/pages/${page_id}`, { method: "PATCH", body });
+        },
+    };
+    // Databases
+    databases = {
+        query: (params) => {
+            const { database_id, ...body } = params;
+            return this.request(`/databases/${database_id}/query`, { method: "POST", body });
+        },
+    };
+    // Blocks
+    blocks = {
+        children: {
+            list: (params) => {
+                const { block_id, ...query } = params;
+                return this.request(`/blocks/${block_id}/children`, {
+                    query: query,
+                });
+            },
+            append: (params) => {
+                const { block_id, ...body } = params;
+                return this.request(`/blocks/${block_id}/children`, { method: "PATCH", body });
+            },
+        },
+    };
+    // Comments
+    comments = {
+        create: (params) => {
+            return this.request("/comments", { method: "POST", body: params });
+        },
+    };
+    // Search
+    search = (params) => {
+        return this.request("/search", { method: "POST", body: params || {} });
+    };
+}
+export function createNotionClient() {
+    const token = process.env.NOTION_TOKEN;
+    if (!token) {
+        throw new Error("NOTION_TOKEN environment variable is required. " +
+            "Please set it to your Notion integration token.");
+    }
+    return new NotionClient({ token });
+}