better-notion

better-mcp-notion

日本語 / 日本語

1 つの Markdown ドキュメントで Notion を操作できる MCP サーバーです。

既存の Notion MCP サーバーは単なる API ラッパーであり、1 回の操作に複数回の往復が必要です。better-mcp-notion では **1 つの Markdown ドキュメント（YAML フロントマター＋本文）**を使って、1 回の呼び出しでページの読み取り、作成、更新を行えます。

better-mcp-notion を選ぶ理由

	従来の Notion MCP	better-mcp-notion
ツール	16～22 個のツール	9 個のツール
データベースエントリーの作成	3 回以上の呼び出し（DB を検索、スキーマを取得、ページを作成、ブロックを追加）	1 回の呼び出し
ページの編集	4 回以上の呼び出し（ページを取得、ブロックを取得、ブロックを削除、ブロックを追加）	1 回の呼び出し（読み取り、編集、書き込み）
フォーマット	生の JSON ブロック	Markdown
コンテキストウィンドウ	大きい（ツール定義＋JSON）	小さい

ツール

ツール	説明
read	フロントマター付きの Markdown として Notion ページを読み取ります。depth を指定すると、子ページを再帰的に読み取れます。
write	Markdown からページを作成または更新します。バッチ操作と追加／先頭への挿入に対応しています。
search	キーワードでワークスペースを検索します。Markdown 形式のリストを返します。
list	データベースのレコードをテーブル形式で、または子ページをリスト形式で表示します。自然言語によるフィルターと並べ替えに対応しています。
update	コンテンツを書き換えずにプロパティをすばやく更新します。ページとキーと値のペアを渡すだけです。
schema	データベースのスキーマを表示または変更します。列の追加、削除、名前変更ができます。
comment	ページのコメントを追加または読み取ります。
delete	ページをアーカイブ（ソフト削除）します。
move	ページを別の親ページまたはデータベースに移動します。

クイックスタート

1. Notion インテグレーションを作成する

1. notion.so/profile/integrations にアクセスし、新しいインテグレーションを作成します
2. API キー（ntn_...）をコピーします
3. アクセスするページ／データベースをインテグレーションと共有します（ページメニューの「Connect to」）

2. MCP クライアントに追加する

Claude Code

claude mcp add better-notion -- npx better-mcp-notion

次に、環境変数を設定します：

export NOTION_API_KEY=ntn_your_api_key_here

Claude Desktop / Cursor / Windsurf

MCP 設定ファイル（例：claude_desktop_config.json、.cursor/mcp.json）に追加します：

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "better-mcp-notion"],
      "env": {
        "NOTION_API_KEY": "ntn_your_api_key_here"
      }
    }
  }
}

ソースから実行する

git clone https://github.com/ai-aviate/better-mcp-notion.git
cd better-mcp-notion
npm install && npm run build

次に、MCP 設定で node /path/to/better-mcp-notion/build/index.js を指定します。

使い方

ページを読み取る

read({ page: "https://notion.so/My-Page-abc123def456" })

次の内容が返されます：

---
id: abc123-def456
title: My Page
database: task-db-id
properties:
  Status: In Progress
  Tags:
    - backend
---
## Notes
- Completed API design

ページを作成する

write({ markdown: `
---
title: Meeting Notes
parent: "Project Alpha"
icon: "📝"
---
## Agenda
- Review progress
- Discuss next steps
` })

データベースエントリーを作成する

write({ markdown: `
---
title: Fix login bug
database: "Task Board"
properties:
  Status: In Progress
  Tags:
    - backend
    - urgent
  Due Date: "2026-03-01"
---
## Description
Login fails when password contains special chars.
` })

ページを更新する（read の出力を編集）

write({ markdown: `
---
id: abc123-def456
title: Updated Title
properties:
  Status: Done
---
## New content
Body replaces all existing blocks.
` })

既存のページにコンテンツを追加する

position: "append" を使うと、ページ全体を書き換えずに末尾へコンテンツを追加できます。 新しいコンテンツだけを指定すればよく、既存のコンテンツは保持されます。

write({ markdown: `
---
id: abc123-def456
---
## New section
This is added to the end of the page.
`, position: "append" })

position: "prepend" を使うと、代わりに先頭へコンテンツを追加します。

バッチ作成（1 回の呼び出しで複数のページを作成）

ページを === で区切ります：

write({ markdown: `
---
title: Task 1
database: "Task Board"
properties:
  Status: Todo
---
Task 1 details
===
---
title: Task 2
database: "Task Board"
properties:
  Status: Todo
---
Task 2 details
` })

フィルターを使ってデータベースをクエリする

list({
  target: "Task Board",
  filter: "Status is Done AND Priority is High",
  sort: "Due Date ascending"
})

フィルター構文

• Status is Done / Status = Done - 等しい
• Priority != Low - 等しくない
• Tags contains backend - マルチセレクトに含まれる
• Done is true - チェックボックス
• Score > 80 - 数値比較（>、<、>=、<=）
• Due Date after 2026-03-01 - 日付の前後
• AND で結合：Status is Done AND Priority is High

並べ替え構文

• Due Date ascending または Due Date asc
• Created descending または Created desc

子ページも含めて読み取る

read({ page: "parent-page-id", depth: 2 })

depth: 1 = 現在のページのみ（デフォルト）、2 = 子ページを含む、3 = 孫ページを含む。

プロパティをすばやく更新する

コンテンツを書き換えずにプロパティを更新します：

update({ page: "My Task", properties: { "Status": "Done", "Priority": "High" } })

データベースのスキーマを管理する

// View schema
schema({ database: "Task Board" })

// Add a column
schema({ database: "Task Board", action: "add", property: "Priority", type: "select", options: ["Low", "Medium", "High"] })

// Rename a column
schema({ database: "Task Board", action: "rename", property: "Due", name: "Due Date" })

// Remove a column
schema({ database: "Task Board", action: "remove", property: "Old Column" })

コメント

// Read comments
comment({ page: "abc123" })

// Add a comment
comment({ page: "abc123", body: "Looks good! Ready to ship." })

フロントマターのリファレンス

書き込み（作成／更新）

フィールド	作成	更新	説明
id	-	必須	更新するページ ID
title	推奨	任意	ページタイトル
parent	必須*	無視	親ページ名または ID
database	必須*	無視	データベース名または ID（parent または database のいずれか）
icon	任意	任意	絵文字または画像 URL
cover	任意	任意	カバー画像 URL
properties	任意	任意	データベースのプロパティ（スキーマと照合）

読み取り（出力専用）

フィールド	説明
id	ページ UUID
url	Notion ページ URL
title	ページタイトル
parent / database	親ページまたはデータベース ID
icon、cover	絵文字または画像 URL
properties	すべてのデータベースプロパティ
created、last_edited	タイムスタンプ（読み取り専用）

読み取り専用フィールド（url、created、last_edited、数式など）は、write に渡されても安全に無視されます。

開発

npm run dev          # TypeScript watch mode
npm test             # Run tests
npm run test:watch   # Test watch mode

ライセンス

Elastic License 2.0 (ELv2) — 自由に使用、変更、配布できます。マネージド／ホスト型サービスとして提供することはできません。