better-notion-mcp

Name: better-notion-mcp
Author: n24q02m

ローカル

github.com/n24q02m生産性361 日前に更新

リポジトリ

better-notion-mcp について

better-notion-mcpは、Notionのページ、データベース、ワークスペースを扱うAIエージェント向けのMarkdown中心のMCPサーバーです。複合ツールで一般的な操作の呼び出し数を抑え、自動ページネーションとローカルstdio・リモートHTTPに対応します。

主な機能

01ページの作成、取得、更新、整理
02データベースとページの検索・管理
03ブロック内容の取得と編集
04ワークスペース検索とコメント管理
05MarkdownとNotionブロック間の変換
06自動ページネーションと一括操作

活用シーン

01Markdownの内容からNotionページを作成・更新
02データベースを検索してページを管理
03ワークスペースの内容を検索しコメントを確認
04ファイルのアップロードやブロック内容のMarkdown変換

MCP 対応

ページ、データベース、ブロック、コメントなどのNotion操作をまとめたツールとドキュメントリソースをMCPクライアントに公開します。クライアントはローカルstdioまたは認証方式を設定したリモートHTTPで接続できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "n24q02m-better-notion-mcp-2": {
      "command": "npx",
      "args": [
        "-y",
        "@n24q02m/notion"
      ],
      "env": {
        "NOTION_TOKEN": "<NOTION_TOKEN>"
      }
    }
  }
}

起動コマンドnpx -y @n24q02m/notion

設定が必要な環境変数

NOTION_TOKENシークレットNotion integration token. Create at https://www.notion.so/my-integrations

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

npm@n24q02m/notion2.42.0stdio

ocidocker.io/n24q02m/notion:lateststdio

ツール

掲載時のツール一覧 · 1 日前に更新

パラメーター	型	必須	説明
icon	string	いいえ	アイコン：絵文字（例："(icon)"）、外部 URL（https://...）、または組み込みの略記（name:color、例："document:gray"）
cover	string	いいえ	カバー画像：URL または組み込みの略記（gradient_1..11、solid_red/yellow/blue/beige、nasa_、met_、rijksmuseum_、woodcuts_）
title	string	いいえ	ページタイトル
action	enum	はい	実行する操作create \| get \| get_property \| update \| move \| archive \| restore \| duplicate
content	string	いいえ	Markdown コンテンツ
page_id	string	いいえ	ページ ID（ほとんどの操作で必須）
archived	boolean	いいえ	アーカイブ状態
page_ids	array	いいえ	一括操作用の複数のページ ID
parent_id	string	いいえ	親ページまたはデータベース ID
properties	object	いいえ	ページプロパティ（データベースページ用）。単純な値を使用すると、Notion 形式に自動変換されます。文字列：title/rich_text/select/status。数値：number。ブール値：checkbox。String[]：multi_select。ISO 日付文字列：date。Notion 構造のオブジェクト：そのまま渡します。
property_id	string	いいえ	プロパティ ID（get_property 操作用）
content_limit	number	いいえ	get で返すページブロックの最大数。続きは next_cursor を使用します
append_content	string	いいえ	追加する Markdown
content_cursor	string	いいえ	以前の範囲指定 pages get のカーソル

詳細

notion

mcp-name: io.github.n24q02m/better-notion-mcp

AI エージェント向けの Markdown ファーストな Notion — ページ、データベース、ブロック、コメントを 1 回の呼び出しで扱えます。

n24q02m の関連プロジェクト（クリックして展開）

| プロジェクト | キャッチコピー | タグ | |---|---|---| | [agent-chat-plugin](https://github.com/n24q02m/agent-chat-plugin) | AI エージェント同士が共有フォルダーでチャット — 人間による中継も、オーケストレーターも不要。ワーク... | ツール | | [better-code-review-graph](https://github.com/n24q02m/better-code-review-graph) | トークン効率の高いコードレビューのためのナレッジグラフ — セマンティック検索と呼び出し... | MCP | | [better-drive](https://github.com/n24q02m/better-drive) | .driveignore フィルターを備えた双方向 Google Drive 同期 — rclone エンジン、Windows トレイ | ツール | | [better-email-mcp](https://github.com/n24q02m/better-email-mcp) | AI エージェント向け IMAP/SMTP メール — 読み取り、送信、フォルダー整理、属性管理... | MCP | | [better-godot-mcp](https://github.com/n24q02m/better-godot-mcp) | Godot Engine 用の複合 MCP サーバー — AI 支援ゲーム開発のための17個の複合ツール... | MCP | | [better-notion-mcp](https://github.com/n24q02m/better-notion-mcp) | AI エージェント向けの Markdown 優先 Notion — ページ、データベース、ブロック、コメント... | MCP | | [better-semantic-release](https://github.com/n24q02m/better-semantic-release) | リリース安全性ガードを組み込み済みの python-semantic-release のドロップインフォーク（orp... | ツール | | [better-telegram-mcp](https://github.com/n24q02m/better-telegram-mcp) | AI エージェント向け Telegram — 両方のボ...でメッセージ、チャット、メディア、連絡先を操作 | MCP | | [better-workspace-mcp](https://github.com/n24q02m/better-workspace-mcp) | Google Workspace MCP サーバー（Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...） | MCP | | [claude-plugins](https://github.com/n24q02m/claude-plugins) | n24q02m MCP サーバー向け Claude Code プラグインマーケットプレイス — Web 検索をインストール... | マーケットプレイス | | [imagine-mcp](https://github.com/n24q02m/imagine-mcp) | AI エージェント向けの画像・動画の理解と生成 — Gemini、Open...などに対応 | MCP | | [jules-task-archiver](https://github.com/n24q02m/jules-task-archiver) | batchexecute API を使って Jules タスクを一括操作する Chrome 拡張機能 — ... | ツール | | [mcp-core](https://github.com/n24q02m/mcp-core) | MCP サーバー構築のための共有基盤 — Streamable HTTP トランスポート、OAuth... | MCP | | [mnemo-mcp](https://github.com/n24q02m/mnemo-mcp) | ハイブリッド検索と埋め込み型同期を備えた永続的な AI メモリ。オープンで、無料、無制限... | MCP | | [qwen3-embed](https://github.com/n24q02m/qwen3-embed) | ONNX Runtime と GGUF による軽量な Qwen3 テキスト埋め込みと再ランキング | ライブラリ | | [skret](https://github.com/n24q02m/skret) | サーバー不要のシークレット管理。 | CLI | | [tacet](https://github.com/n24q02m/tacet) | ナレッジ...全体で LLM コストを償却する、自己蒸留型のニューロシンボリックカスケード | ツール | | [web-core](https://github.com/n24q02m/web-core) | 検索、スクレイピング、HTTP セキュリティ、スト...のための共有 Web インフラストラクチャパッケージ | ライブラリ | | [wet-mcp](https://github.com/n24q02m/wet-mcp) | AI エージェント向けのオープンソース MCP サーバー：Web 検索、コンテンツ抽出、ライブラリ... | MCP |

Markdown 入力、Markdown 出力 -- 生の JSON ブロックではなく、人が読みやすいコンテンツを表示します
8 個の複合ツール、39 個のアクション -- Notion の 2 つ以上のアトミックなエンドポイントを連鎖させる代わりに、1 回の呼び出しで実行します（さらに config と help もあります）
自動ページネーションと一括操作 -- カーソルの手動処理やループは不要です
段階的なトークン最適化 -- 説明の圧縮とオンデマンドの help ツールにより、約 77% 削減します
デュアルトランスポート -- ローカル stdio（インテグレーショントークン）またはリモート HTTP（ユーザーごとの、あるいは共有のベアラートークン）

インストール

npx（Node.js >= 24）と、Notion インテグレーショントークン（ntn_ で始まります。https://www.notion.so/my-integrations から取得）を使って実行します。

// MCP client config (e.g. .mcp.json / Claude Code / Cursor)
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/notion@latest"],
      "env": { "NOTION_TOKEN": "ntn_your_token_here" }
    }
  }
}

パッケージ名は @n24q02m/notion です（旧パッケージ名は @n24q02m/better-notion-mcp です。旧パッケージは最後のリリース後に更新を終了します）。MCP Registry の ID は io.github.n24q02m/better-notion-mcp のままで、旧コマンド better-notion-mcp は notion のエイリアスとして維持されます。

または、公開済みの Docker イメージを実行します（stdio）。

docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/notion:latest

インストール一覧

クライアント	インストール
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install better-notion-mcp@n24q02m-plugins`（stdio。`NOTION_TOKEN` の入力を求められます）、または `.mcp.json`／クライアント設定の `mcpServers` エントリ
Codex CLI	`~/.codex/config.toml` の `[mcp_servers.notion]` ブロック（stdio の `command`／`args` または HTTP の `type`／`url`）
OpenCode	`opencode.json` の `mcpServers` ブロック
Cursor／Windsurf／Gemini CLI／その他の MCP クライアント	クライアントの設定にある `mcpServers` JSON（上記の例と同じ形式）

クライアントごとの詳しい手順については、mcp.n24q02m.com/servers/better-notion-mcp/setup/ をご覧ください。クライアントごとの設定（Claude Code、Codex、Gemini CLI、Cursor、Windsurf）と HTTP モードについては、ドキュメントのセクションをご覧ください。

CLI

パッケージをインストールすると、notion バイナリ（および旧名 better-notion-mcp のエイリアス）が利用できるようになります。npx で実行するか、グローバルインストール後に実行してください。引数を指定せずに実行すると MCP サーバーが起動し、標準入力／標準出力でプロトコルを通信します。そのため、通常は手動ではなく MCP クライアントから起動します。サブコマンドには、Notion インテグレーショントークンを保存する auth と、共有 hull CLI の config、status、logout、doctor、token があります。

# Start the stdio server (default transport; requires NOTION_TOKEN)
NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/notion@latest

# Start the remote HTTP server (bearer token) instead of stdio
npx --yes @n24q02m/notion@latest --http

引数／環境変数	動作
(なし)	stdio トランスポート（デフォルト）。`NOTION_TOKEN` が必要です
`--http`	HTTP トランスポート。認証方式は `MCP_AUTH_MODE` で指定します（デフォルトは `multi`、または `token`、`no-auth`）

環境変数の全項目については、設定をご覧ください。

リモート（HTTP モード）

HTTP トランスポートでデプロイすると、サーバーはベアラートークン認証で保護されたリモートエンドポイントになります。サーバー設定にインテグレーショントークンは必要ありません。リモート HTTP サーバーに対応した MCP クライアントから、デプロイ先のホストを指定してください。

// MCP client config -- remote HTTP (bearer token)
{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

デフォルトの multi モードでは、各ユーザーがユーザーファイル（MCP_USERS_FILE。デフォルトは ~/.hull/users.toml）に登録され、それぞれ独自のトークンと認証情報の名前空間を持ちます。token モードでは、すべてのクライアントが 1 つのトークンを共有し、その scrypt ハッシュは MCP_AUTH_TOKEN_HASH に設定します。このようなインスタンスの構築方法については、セルフホスト（リモートモード）をご覧ください。

Smithery

リポジトリには、Smithery 用の smithery.yaml 設定が含まれています。Smithery はサーバーを stdio（npx -y @n24q02m/notion）で起動し、インストール時の設定は不要です。実行時に NOTION_TOKEN または config ツールを使って Notion の認証情報を指定してください（設定を参照）。

ステータス

2026-05-02 -- アーキテクチャの安定化に関する更新

ここ数か月、認証情報の処理とデーモンブリッジの自動起動パターンに大きな変更が続きました。その結果、複数プロセス間の競合、ブラウザータブの大量起動、プラグイン間でのセットアップ UX の不統一が発生していました。アーキテクチャは現在安定しています。モードはシンプルな 2 種類（stdio と HTTP）で、デーモンブリッジ層はなく、stdio からの自動起動もありません。

不安定な期間が続いたことをお詫びします。以前のバージョンで問題が発生していた場合は、最新リリースに更新し、現在のセットアップガイドに従ってください。以前必要だった回避策の大半は、もう必要ありません。

同じ作者による関連プラグイン：

wet -- ウェブ検索とコンテンツ抽出

mnemo -- 永続的な AI メモリ

imagine-mcp -- 画像・動画の理解と生成

email -- メール管理

telegram -- Telegram

better-godot-mcp -- Godot Engine

crg -- コードレビュー用ナレッジグラフ

すべてのプラグインで同じアーキテクチャを採用しています。一度インストールすれば、習得したパターンをほかのプラグインにも応用できます。

ドキュメント

詳細なドキュメントは mcp.n24q02m.com/servers/better-notion-mcp/ をご覧ください。

セットアップ -- Claude Code、Codex、Gemini CLI、Cursor、Windsurf、mcp.json 向けのインストール方法
モードの概要 -- stdio（ローカル、インテグレーショントークン）と HTTP（リモート、ベアラートークン）
マルチユーザーのセットアップ -- ユーザーごとの認証情報名前空間（HTTP モード）

AI エージェントでインストール -- 次の内容を AI コーディングエージェントに貼り付けてください。

次の手順に従って MCP サーバー notion をインストールしてください。 https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md

ツール

8 つの複合 Notion ツール（39 個のアクション）に加え、2 つのインフラストラクチャツール（config、help）があります。

ツール	アクション	説明
`pages`	`create`、`get`、`get_property`、`update`、`move`、`archive`、`restore`、`duplicate`	ページの作成、読み取り、更新、整理
`databases`	`create`、`get`、`query`、`create_page`、`update_page`、`delete_page`、`create_data_source`、`update_data_source`、`update_database`、`list_templates`	データベースの CRUD と、データベース内のページ管理
`blocks`	`get`、`children`、`append`、`update`、`delete`	ブロックコンテンツの読み取りと操作
`users`	`list`、`get`、`me`、`from_workspace`	ユーザー情報の一覧表示と取得
`workspace`	`info`、`search`	ワークスペースのメタデータと、ワークスペースを横断した検索
`comments`	`list`、`get`、`create`	ページのコメントとディスカッションへの返信
`content_convert`	`markdown-to-blocks`、`blocks-to-markdown`	Markdown と Notion ブロックの相互変換（`direction` パラメーターを使用）
`file_uploads`	`create`、`send`、`complete`、`retrieve`、`list`	Notion へのファイルのアップロード（単一またはマルチパート）
`config`	`status`、`setup_status`、`setup_start`、`setup_reset`、`setup_complete`、`set`、`cache_clear`	認証情報の状態と設定のライフサイクルの確認・管理
`help`	-	任意の複合ツールに関する完全なドキュメントを取得（`tool_name` パラメーター）

MCP リソース

URI	説明
`notion://docs/pages`	ページ操作のリファレンス
`notion://docs/databases`	データベース操作のリファレンス
`notion://docs/blocks`	ブロック操作のリファレンス
`notion://docs/users`	ユーザー操作のリファレンス
`notion://docs/workspace`	ワークスペース操作のリファレンス
`notion://docs/comments`	コメント操作のリファレンス
`notion://docs/content_convert`	コンテンツ変換のリファレンス
`notion://docs/file_uploads`	ファイルアップロードのリファレンス

設定

変数	必須	デフォルト	説明
`NOTION_TOKEN`	はい（stdio）	-	Notion インテグレーショントークン
`TRANSPORT_MODE` / `MCP_TRANSPORT`	いいえ	`stdio`	リモートモードにするには、いずれかに `http` を設定します（または `--http` を渡します）
`MCP_AUTH_MODE`	いいえ（http）	`multi`	`multi`（`MCP_USERS_FILE` のユーザー別トークン）、`token`（共有トークン1つ。`MCP_AUTH_TOKEN_HASH` が必要）、または `no-auth`（信頼できる環境／ローカルでの使用のみ）
`MCP_USERS_FILE`	いいえ（http、multi）	`~/.hull/users.toml`	`multi` モード用のユーザーファイル
`MCP_AUTH_TOKEN_HASH`	はい（token モード）	-	共有トークンの `scrypt$` ハッシュ（`token hash` で生成）
`MCP_RPM`	いいえ（token モード）	-	token モードでの任意の1分あたりリクエスト上限
`PORT`	いいえ	`0`（OS による割り当て）	サーバーポート。固定ポートにバインドするには明示的に設定します（例：`8080`）
`HOST`	いいえ	`127.0.0.1`	バインドアドレス（http モード）

セルフホスト（リモートモード）

HTTP サーバーを独自のホストで実行し、MCP_AUTH_MODE で認証モードを選択します。

multi（デフォルト）：MCP_USERS_FILE に各ユーザーを登録します。各ユーザーの Notion トークンは、それぞれの名前空間（~/.better-notion/subs/<ns>/config.json）に保存されます。
token：共有ベアラートークンを1つ使用します。token hash でハッシュを生成し、MCP_AUTH_TOKEN_HASH として渡します。
no-auth：ベアラーチェックを行いません。信頼できるローカルネットワークでのみ使用してください。

docker run -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -e PORT=8080 \
  -e MCP_AUTH_MODE=token \
  -e MCP_AUTH_TOKEN_HASH='scrypt$...' \
  n24q02m/notion:latest

Docker Compose（ループバック）

docker-compose.http.yml は http イメージターゲットをビルドし、ホストのループバックインターフェース（127.0.0.1:8081）のみに公開します。そのため、サーバーが他のマシンから直接アクセスされることはありません。

export MCP_AUTH_MODE=token
export MCP_AUTH_TOKEN_HASH='scrypt$...'
docker compose -f docker-compose.http.yml up

サーバーは http://localhost:8081/mcp でリッスンします。外部に公開するには、ループバックポートの前段に独自の TLS リバースプロキシを設置してください。

リリースイメージはマルチアーキテクチャ（amd64 + arm64）で Docker Hub（n24q02m/notion）と GHCR（ghcr.io/n24q02m/notion）に公開されています。n24q02m がホストする HTTP エンドポイントはありません。

比較

各分野で notion が直接の競合製品と比べてどのような位置にあるかを示します。

機能	notion	makenotion/notion-mcp-server	suekou/mcp-notion-server	awkoy/notion-mcp-server
Markdown の入出力	はい（ページとブロックで往復変換）	いいえ（生の Notion JSON）	一部（実験的、追記とオプトイン変換）	はい（往復変換 + GFM）
複合ツール設計	はい（8つの複合ツール、39のアクション）	いいえ（エンドポイントに対応した22のツール）	一部（簡略化されたツール + 生の JSON ツール）	はい（2つのディスパッチツール、35以上の操作）
Notion へのファイルアップロード	はい（`file_uploads`、単一およびマルチパート）	いいえ	いいえ	はい（`upload_file`、単一およびマルチパート）
コメント	はい（`comments`：一覧／取得／作成）	はい	はい	はい
リモート HTTP + ベアラートークン認証	はい（ユーザー別名前空間または共有トークン）	一部（HTTP + ベアラートークン）	いいえ（stdio のトークンのみ）	いいえ（stdio のトークンのみ）
セルフホスト可能	はい（Docker、独自のベアラートークン）	はい	はい	はい
ライセンス	Apache-2.0	?	MIT	MIT

セキュリティ

ベアラートークン認証 -- ユーザー別トークン（multi）または scrypt でハッシュ化した共有トークン1つ（token）
レート制限 -- HTTP トランスポートで IP あたり毎分120リクエスト
セッション所有者の紐付け -- IP チェック + 保留中のトークン紐付けに対する TTL
Null 安全性 -- Notion API の特異な挙動に対応します（comments.list の 404、未定義の rich_text）

ソースからビルド

git clone https://github.com/n24q02m/notion.git
cd notion
bun install
bun run dev

信頼モデル

認証情報が n24q02m に送信されることはありません。ホスト型エンドポイントはありません。

モード	保存場所	保護	データを読み取れる人
HTTP セルフホスト（`multi`）	サーバーホスト上の `~/.better-notion/subs/<ns>/config.json`	サーバーのデータディレクトリ内でファイルモード 0600	サーバーの運用者と、そのホストへのアクセス権を持つ人
HTTP セルフホスト（`token`）	サーバーホスト上の `~/.better-notion/config.json`	サーバーのデータディレクトリ内でファイルモード 0600	サーバーの運用者と、そのホストへのアクセス権を持つ人
stdio（ローカル）	`~/.better-notion/config.json`	ファイルモード 0600。マシンキーは `~/.better-notion/.secret` に保存	お使いの OS ユーザーのみ

ライセンス

Apache-2.0 -- LICENSE を参照してください。

Markdown 対応

ログインしてコメント

基本情報

作者: n24q02m
言語: node
バージョン: 2.42.0
トランスポート: stdio
掲載日: 2026年10月27日
最終更新: 1 日前
公式 Registry: io.github.n24q02m/better-notion-mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。