Notion Private API MCP

Notion Private API MCP Server

Notion の非公開 API（token_v2）を使用して構築された非公式の Notion MCP サーバーです。 Claude Desktop、Claude Code、Cursor、およびその他の MCP クライアントから、連携トークンを使わず、ページを 1 つずつ共有することもなく、Notion ワークスペース全体を完全に読み書きできます。

公式 Notion API を使用して構築されたサーバーとは異なり、このサーバーはブラウザーのセッションクッキーで認証するため、LLM エージェントは Notion での設定なしに、アカウントから見えるあらゆるページをすぐに検索、読み取り、作成、編集できます。公式の @modelcontextprotocol/sdk（stdio トランスポート）を使用して構築されています。

---

このサーバーを選ぶ理由

	このサーバー（非公開 API）	公式 Notion API / MCP
Notion での設定	不要 — ブラウザーのクッキーだけ	連携を作成し、各ページを共有
アクセス範囲	アカウントから見えるすべてのもの	連携と明示的に共有されたページのみ
認証	token_v2 セッションクッキー	連携トークン / OAuth
最適な用途	個人の自動化、ワークスペース全体を扱うエージェント	本番アプリ、マルチユーザー、公式サポート
安定性	⚠️ 不安定で、ドキュメントなし	✅ 安定しており、サポート対象

連携の権限設定に悩まず、自分のワークスペースを扱うエージェントを使いたいだけなら、これが最も手早い方法です。本番環境やマルチテナントアプリには、 公式 Notion MCP サーバーを使用してください。

---

目次

• 重要：非公開 API を使用
• クイックスタート
• ツール
• 設定
• MCP クライアントでの使用
• プロンプトの例
• コンテンツの作成
• トラブルシューティング / FAQ
• コントリビューション
• ライセンス · 免責事項

---

⚠️ 重要：Notion の非公開 API を使用します

このサーバーは公式の公開 API ではなく、Notion の非公開内部 API（https://www.notion.so/api/v3）と通信します。

• 認証にはブラウザーのクッキー（token_v2）を使用します。これは実質的にアカウントのパスワードです。絶対にコミットしないでください。
• Notion はいつでもこの API を変更したり、動作しなくしたりする可能性があり、使用が Notion の利用規約に違反する場合があります。
• 本質的に不安定で、本番環境での使用を想定していません。ご自身のデータを使い、ご自身の責任で使用してください。

---

クイックスタート

git clone https://github.com/kirvigen/notion-private-api-mcp.git
cd notion-private-api-mcp
npm install
export NOTION_TOKEN_V2='your_token_v2'   # see "Configuration" below
npm start

その後、MCP クライアント（Claude Desktop / Claude Code）に登録してください。

---

ツール

ツール	説明
get_page	ページのブロックとメタデータを読み取ります
get_block	単一のブロックを読み取ります
get_block_children	ページまたはブロックの直接の子ブロックを読み取ります
get_style_documentation	対応するブロックタイプとインライン注釈の一覧（複雑なページを作成する前に呼び出してください）
markdown_to_blocks	Markdown が簡略化されたブロック JSON にどのように変換されるかをプレビューします
create_page	ブロックまたは Markdown から、別のページの子ページを作成します
append_blocks	ページの末尾、または指定したブロックの後に、ブロックや Markdown を追加します
replace_page_content	ページの直接の子ブロックを置き換えます
update_block_text	ブロックのプレーンテキストコンテンツを置き換えます（例：コードブロック）
delete_blocks	ページの直接の子ブロックを削除（アーカイブ）します
sync_markdown_file	ローカルの Markdown ファイルからページを作成または置き換えます

ツールのパラメーターは src/server.js で定義されています。

---

設定

環境変数のみで設定します。

変数	必須	説明
NOTION_TOKEN_V2	✅	Notion のセッション Cookie（token_v2）
NOTION_PRIVATE_API_BASE	—	API ベース URL（デフォルト：https://www.notion.so）

token_v2 の取得方法

1. ブラウザーで Notion にログインします：https://www.notion.so
2. DevTools（F12）を開き、Application → Cookies → https://www.notion.so に移動します
3. token_v2 Cookie の値をコピーします。

🔒 パスワードと同様に取り扱ってください。シェル環境変数または追跡対象外の .env に保存し、決してコミットしないでください。

cp .env.example .env   # then edit .env

---

MCP クライアントでの使用方法

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "notion-private": {
      "command": "node",
      "args": ["/absolute/path/to/notion-private-api-mcp/src/server.js"],
      "env": { "NOTION_TOKEN_V2": "your_token_v2" }
    }
  }
}

Claude Code

claude mcp add notion-private \
  --scope local \
  --env NOTION_TOKEN_V2='your_token_v2' \
  -- node /absolute/path/to/notion-private-api-mcp/src/server.js

ヘルパースクリプト ./run-desktop.sh と ./run-codex.sh はリポジトリのパスを自動で解決し、 /tmp にログを出力します。

---

プロンプトの例

接続したら、エージェントに話しかけるだけです：

• 「Notion で『Q3 Roadmap』ページを探して、要約してください。」
• 「 の下に、今日のアクション項目を含む『Meeting notes』という子ページを作成してください。」
• 「次の 3 つのタスクを に TODO リストとして追加してください…」
• 「ローカルの CHANGELOG.md をリリースノートのページに同期してください。」

---

コンテンツの作成

書き込みを行うツールでは、プレーンな JSON の簡易ブロック形式を使用できます：

[
  { "type": "heading_1", "text": "Release Notes" },
  { "type": "paragraph", "text": "First paragraph." },
  { "type": "to_do", "text": "Ship the feature", "checked": true },
  { "type": "toggle", "text": "Details", "children": [
    { "type": "bulleted_list_item", "text": "Item one" }
  ]}
]

対応しているタイプ：paragraph、heading_1／2／3、bulleted_list_item、numbered_list_item、 to_do、toggle、quote、callout、code、divider。

Markdown も渡すことができます（安定しているサブセット：見出し、段落、箇条書き／番号付きリスト、 タスク項目、引用、フェンス付きコード、水平線）。権威ある機械可読カタログを参照するには、クライアントから get_style_documentation を呼び出してください。ネストされたリスト、表、インライン書式にはまだ対応していません。

---

トラブルシューティング／FAQ

token_v2 はどこで取得できますか？ token_v2 の取得方法 を参照してください。

NOTION_TOKEN_V2 is required — サーバーを起動するプロセスに環境変数が設定されていません （シェルだけでなく、MCP クライアントの env ブロックを確認してください）。

トークンが使えなくなりました — Notion のセッションが終了すると（ログアウト、パスワード変更、長期間の非アクティブ状態など）、token_v2 の有効期限が切れます。Cookie を新たに取得して更新してください。

MemcachedCrossCellError — 複数セルのワークスペースで発生する、一時的な Notion のルーティングエラーです。クライアントはすでに再試行し、loadPageChunk にフォールバックします。このエラーが発生した場合は、呼び出しを再試行してください。

これは Notion の利用規約に違反しますか？ ドキュメント化されていない内部 API を使用しています。ご自身のアカウントとデータに限り、ご自身の責任で使用してください。

---

プロジェクト構成

src/
├── server.js         # MCP server: tool registration + stdio transport
├── notion-client.js  # Private-API client (cookie auth, transactions, retries)
├── notion-blocks.js  # Builds Notion block trees from simplified blocks
├── markdown.js       # Markdown → simplified-block parser
└── style-docs.js     # Catalog returned by get_style_documentation

---

コントリビューション

イシューや PR を歓迎します。これが時間の節約になった場合は、リポジトリに ⭐ を付けてください。ほかの人に見つけてもらううえで、本当に役立ちます。

---

ライセンス

MIT © kir.vigen

免責事項

Notion Labs, Inc. とは提携していません。ドキュメント化されていない内部 API に依存しています。使用すると、アカウントの制限や API の変更による動作不能を含む、あらゆるリスクを受け入れたことになります。 ご自身のデータに限り使用してください。