Notion MCP Server (Official)

Notion MCP Server (Official) とは？

Notion MCP Server (Official) は、Notion が公開しているオープンソースでセルフホスト型の notion mcp server（@notionhq/notion-mcp-server）です。Notion API を MCP ツールに変換し、AI クライアントがページ、データベース、コメント、ブロックを検索・読み取り・作成・更新できるようにします。

Notion は現在、このリポジトリを積極的なメンテナンス対象外としており、代わりにホスト型の Remote Notion MCP（https://mcp.notion.com/mcp）を推奨しています。このページでは、本掲載が対象とするローカルサーバーと、Notion が案内するホスト型エンドポイントの両方を説明します。

Notion MCP Server (Official) の使い方

次の 2 つのセットアップ方法から選びます。

• Remote Notion MCP（Notion 推奨）：インストール不要です。クライアントに https://mcp.notion.com/mcp を追加し、OAuth でサインインします。Notion 上の既存の権限がそのまま使われます。
• ローカルサーバー（このリポジトリ）：npx または Docker で実行します。internal integration token（ntn_...）で認証し、ページをその integration に自分で共有する必要があります。

ローカル設定：トークンとページへのアクセス

1. https://www.notion.so/profile/integrations を開き、internal integration を作成します。
2. integration の Access タブで、使用を許可するページとデータベースを選びます。ページを開き、右上の三点メニューから Connect to integration を選ぶ方法もあります。
3. integration secret をコピーします。読み取り専用にする場合は、Capabilities で "Read content" のみを有効にします。

Claude Desktop

claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json）にサーバーを追加します。

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Docker を使う場合は、公式イメージ mcp/notion も利用できます（README を参照）。

Cursor

ローカルサーバーの場合は、同じ JSON を .cursor/mcp.json に記述します。ホスト型サーバーの場合は次を使います。

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

その後、Cursor のサイドバーで Customize を開き、Notion を有効にして OAuth フローを完了します。

Claude Code

Notion のドキュメントでは、Claude Code からホスト型エンドポイントに接続する方法が案内されています。

claude mcp add --transport http notion https://mcp.notion.com/mcp

続いて Claude Code で /mcp を実行し、OAuth フローに従います。

VS Code

.vscode/mcp.json を作成します。

{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

コマンドパレットで MCP: List Servers を実行し、Notion を起動してサインインします。

Codex

~/.codex/config.toml に次を追加し、codex mcp login notion を実行します。

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

ローカルサーバーの README には、Zed と GitHub Copilot CLI（~/.copilot/mcp-config.json）向けの設定も掲載されています。

Notion MCP Server (Official) の主な機能

• Notion（makenotion）が MIT ライセンスで公開。npm パッケージは @notionhq/notion-mcp-server、Docker Hub イメージは mcp/notion です。
• ツールは Notion の OpenAPI 仕様から生成され、各ツールが 1 つの Notion API エンドポイントに対応します。
• バージョン 2.0 は Notion API 2025-09-03 と data sources モデル（database_id の代わりに data_source_id）を使用します。
• ページ内容を Markdown で読み書きでき、ブロック JSON よりもトークンを大幅に節約できます。
• デフォルトは STDIO トランスポートです。--transport http で Streamable HTTP を利用でき、その場合は bearer token（--auth-token または AUTH_TOKEN）が必要です。
• --enable-token-passthrough を使うと、セッションごとの Notion-Token ヘッダーにより 1 つの HTTP デプロイで複数の integration を扱えます。
• 一部の操作は意図的に提供されていません。たとえば、データベースの削除はできません。

Notion MCP Server (Official) のツール

ローカルサーバーのツールは、いくつかのグループに分けられます。

• 検索とユーザー：post-search はページと data source を検索します。get-users、get-user、get-self はワークスペースのメンバーとボットユーザーを取得します。
• ページ：post-page、retrieve-a-page、patch-page、retrieve-a-page-property、move-page でページの作成・取得・更新・移動を行います。
• Markdown コンテンツ：retrieve-page-markdown と update-page-markdown はページ全体を Markdown として読み書きします。
• ブロック：get-block-children、patch-block-children、retrieve-a-block、update-a-block、delete-a-block はページ内容をブロック単位で扱います。
• データベースと data source：query-data-source（フィルターと並べ替え）、retrieve-a-data-source、create-a-data-source、update-a-data-source、list-data-source-templates、retrieve-a-database。
• コメント：create-a-comment と retrieve-a-comment。

ホスト型の Remote Notion MCP には、notion-search、notion-fetch、notion-create-pages、notion-update-page、notion-query-data-sources など、AI エージェント向けに設計された別のツール群があります。

Notion MCP Server (Official) のユースケース

• チャットからページにコメントする："Comment 'Hello MCP' on page 'Getting started'"。クライアントは検索を呼び出したあと、コメントのエンドポイントを呼び出します。
• 親ページの下にページを作成する："Add a page titled 'Notion MCP' to page 'Development'"。
• コーディング中に ID でページを読み込み、コンテキストとして使う："Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2"。
• タスクやバグのデータベースをフィルターと並べ替えで検索し、結果を要約する。
• Markdown ツールで議事録や仕様書を書き直す（ブロック JSON を扱う必要はありません）。

Notion MCP Server (Official) と代替ツールの比較

• Remote Notion MCP（ホスト型）：Notion が推奨する mcp notion の選択肢です。OAuth と自分の権限を使い、Notion と接続済みアプリをまたいだセマンティック検索に対応し、継続的にサポートされています。ローカルプロセスは不要です。AI 検索やヘッドレス利用向けの MCP token など一部の機能は、Business または Enterprise プランが必要です。
• このローカルサーバー：トークンベースのヘッドレスアクセスが必要な場合や、セルフホストしたい場合に向いています。Notion は積極的なサポートを行っておらず、将来提供終了になる可能性があるとしています。
• コミュニティ製サーバー：たとえば awkoy/notion-mcp-server は非公式プロジェクトで、npm では notion-mcp-server として公開されています。Notion のコードベースとは別物です。

Notion MCP Server (Official) のトラブルシューティング

• ページやデータベースが見つからない：integration は共有されたコンテンツしか参照できません。integration の Access タブでページを追加するか、Connect to integration を使います。
• 古いデータベースツールがない：v2.0 では post-database-query、update-a-database、create-a-database が query-data-source、update-a-data-source、create-a-data-source に置き換えられました。古い名前をハードコードしたプロンプトを更新してください。
• HTTP リクエストが拒否される：Streamable HTTP ではすべてのリクエストに Authorization: Bearer <token> が必要です。--auth-token を指定しない場合、サーバーは生成したトークンを一時ファイルに書き出します。隔離されたネットワーク以外では --unsafe-disable-auth を使わないでください。
• クライアントがローカルサーバーにしか対応していない：mcp-remote ブリッジを使えばホスト型サーバーに接続できます："command": "npx", "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"]。
• ホスト型の OAuth に失敗する：クライアントの接続を解除して再接続し、対象ワークスペースでのアクセス権を確認します。ワークスペースのゲストは接続できません。