Notion MCP

公式

Notionのページ、データベース、ワークスペースコンテンツをAIエージェントから検索、読み取り、作成、更新するための公式Notion MCPサーバー。

GitHub

4.5k

Notion MCPで何ができますか？

タイトルでページやデータソースを検索 — post-search を使用して、ワークスペース全体のページやデータソースを名前で検索します。
ページのコンテンツをMarkdownとして読み取る — retrieve-page-markdown を使用してページの全コンテンツを取得します。オプションで会議の文字起こしを含めることもできます。
ページのコンテンツをMarkdownで編集 — update-page-markdown を使用してページコンテンツを上書きまたは検索置換します。
フィルターと並べ替えでデータソースをクエリ — query-data-source を介してデータソースに対して構造化クエリを実行します。
親ページまたはデータソース内に新しいページを作成 — post-page を使用してページを追加し、page_id または database_id の親を指定します。
ページを別の親の場所に移動 — move-page を使用してページを移動し、ワークスペースを再編成します。

ドキュメント

Notion MCP サーバー

[!NOTE]

以下の改善点を備えたリモート MCP サーバー Notion MCP を導入しました。

標準 OAuth による簡単なインストール。JSON や API トークンを扱う必要はもうありません。

Markdown でのページ編集を含む、AI エージェント向けに最適化された強力なツール。これらのツールはトークン消費の最適化を念頭に設計されています。

詳細と開始方法については、Notion MCP ドキュメントをご覧ください。

現在、Notion MCP（リモート）を優先し、積極的なサポートのみを提供しています。その結果：

このローカル MCP サーバーリポジトリは、将来廃止される可能性があります。

ここでの Issue やプルリクエストは積極的には監視されていません。

リモート MCP に関する Issue をここで報告しないでください。代わりに Notion サポートにお問い合わせください。

notion-mcp-sm

このプロジェクトは、Notion API 用の MCP サーバーを実装します。

mcp-demo

⚠️ バージョン 2.0.0 の破壊的変更

バージョン 2.0.0 は Notion API 2025-09-03 に移行し、データベースの主要な抽象化としてデータソースが導入されます。

変更点

削除されたツール (3):

post-database-query - query-data-source に置き換えられました
update-a-database - update-a-data-source に置き換えられました
create-a-database - create-a-data-source に置き換えられました

新しいツール (7):

query-data-source - フィルターとソートを使用してデータソース（データベース）をクエリ
retrieve-a-data-source - データソースのメタデータとスキーマを取得
update-a-data-source - データソースのプロパティを更新
create-a-data-source - 新しいデータソースを作成
list-data-source-templates - データソースで利用可能なテンプレートを一覧表示
move-page - ページを別の親の場所に移動
retrieve-a-database - データソース ID を含むデータベースメタデータを取得

パラメータの変更:

すべてのデータベース操作で、database_id の代わりに data_source_id を使用するようになりました
検索フィルターの値が ["page", "database"] から ["page", "data_source"] に変更されました
ページ作成で、page_id と database_id の両方の親（データソース用）がサポートされるようになりました

移行は必要ですか？

コードの変更は不要です。 MCP ツールはサーバー起動時に自動的に検出されます。v2.0.0 にアップグレードすると、AI クライアントは新しいツール名とパラメータを自動的に認識します。古いデータベースツールは使用できなくなりました。

古いデータベースツールを参照するハードコードされたツール名やプロンプトがある場合は、新しいデータソースツールを使用するように更新してください。

古いツール (v1.x)	新しいツール (v2.0)	パラメータの変更
`post-database-query`	`query-data-source`	`database_id` → `data_source_id`
`update-a-database`	`update-a-data-source`	`database_id` → `data_source_id`
`create-a-database`	`create-a-data-source`	変更なし (`parent.page_id` を使用)

注: retrieve-a-database は引き続き利用可能で、データソース ID のリストを含むデータベースメタデータを返します。特定のデータソースのスキーマとプロパティを取得するには、retrieve-a-data-source を使用してください。

現在のツール総数: 22 (v1.x では 19 でした)

Markdown としてのページコンテンツ

サーバーは、ブロック JSON の代わりに拡張 Markdown としてページコンテンツを操作するための 2 つのツールを公開しており、AI エージェントにとってトークン効率が大幅に向上します。

retrieve-page-markdown — ページの全コンテンツを Markdown として読み取ります (GET /v1/pages/{page_id}/markdown)。会議メモのトランスクリプトをインライン化するには include_transcript: true を渡します。
update-page-markdown — Markdown でページのコンテンツを編集します (PATCH /v1/pages/{page_id}/markdown)。ページ全体を上書きする場合は replace_content を、対象を絞った検索と置換の編集には update_content を優先してください。

これらのエンドポイントには Notion API バージョン 2026-03-11 が必要です。サーバーは OpenAPI 仕様から 操作ごとに Notion-Version ヘッダーを取得するようになったため、これらのツールは 2026-03-11 を使用し、残りの API は引き続き 2025-09-03 を使用します。設定は不要です。OPENAPI_MCP_HEADERS を介して自分で Notion-Version を設定した場合、その値がすべてのツールで優先されます。

インストール

1. Notion でのインテグレーションの設定

https://www.notion.so/profile/integrations にアクセスし、新しい内部インテグレーションを作成するか、既存のものを選択します。

Creating a Notion Integration token

Notion API の公開範囲を制限していますが（たとえば、MCP 経由でデータベースを削除することはできません）、LLM に公開することによるワークスペースデータへのリスクはゼロではありません。セキュリティを重視するユーザーは、インテグレーションの Capabilities をさらに設定することをお勧めします。

たとえば、「設定」タブで「コンテンツの読み取り」アクセスのみを付与することで、読み取り専用のインテグレーショントークンを作成できます。

Notion Integration Token Capabilities showing Read content checked

2. コンテンツのインテグレーションへの接続

関連するページとデータベースがインテグレーションに接続されていることを確認してください。

これを行うには、内部インテグレーション設定の アクセス タブにアクセスします。アクセスを編集し、使用するページを選択します。

Integration Access tab

Edit integration access

または、ページアクセスを個別に付与することもできます。対象のページにアクセスし、3 つのドットをクリックして、「インテグレーションに接続」を選択する必要があります。

Adding Integration Token to Notion Connections

3. クライアントへの MCP 設定の追加

npm の使用

Cursor と Claude

.cursor/mcp.json または claude_desktop_config.json (MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json) に以下を追加します。

オプション 1: NOTION_TOKEN の使用 (推奨)

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

オプション 2: OPENAPI_MCP_HEADERS の使用 (高度なユースケース向け)

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
      }
    }
  }
}

Zed

settings.json に以下を追加します。

{
  "context_servers": {
    "some-context-server": {
      "command": {
        "path": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": {
          "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\" }"
        }
      },
      "settings": {}
    }
  }
}

GitHub Copilot CLI

Copilot CLI を使用して、MCP サーバーを対話的に追加します。

/mcp add

または、設定ファイル ~/.copilot/mcp-config.json を作成または編集して、以下を追加します。

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

詳細については、Copilot CLI ドキュメントを参照してください。

Docker の使用

Docker で MCP サーバーを実行するには、2 つのオプションがあります。

オプション 1: 公式 Docker Hub イメージの使用

.cursor/mcp.json または claude_desktop_config.json に以下を追加します。

NOTION_TOKEN の使用 (推奨):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTION_TOKEN",
        "mcp/notion"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

OPENAPI_MCP_HEADERS の使用 (高度なユースケース向け):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "OPENAPI_MCP_HEADERS",
        "mcp/notion"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_****\",\"Notion-Version\":\"2025-09-03\"}"
      }
    }
  }
}

このアプローチでは：

公式 Docker Hub イメージを使用します
環境変数を介して JSON エスケープを適切に処理します
より信頼性の高い設定方法を提供します

オプション 2: Docker イメージのローカルビルド

Docker イメージをローカルでビルドして実行することもできます。まず、Docker イメージをビルドします。

docker compose build

次に、.cursor/mcp.json または claude_desktop_config.json に以下を追加します。

NOTION_TOKEN の使用 (推奨):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "NOTION_TOKEN=ntn_****",
        "notion-mcp-server"
      ]
    }
  }
}

OPENAPI_MCP_HEADERS の使用 (高度なユースケース向け):

{
  "mcpServers": {
    "notionApi": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "OPENAPI_MCP_HEADERS={\"Authorization\": \"Bearer ntn_****\", \"Notion-Version\": \"2025-09-03\"}",
        "notion-mcp-server"
      ]
    }
  }
}

ntn_**** をインテグレーションシークレットに置き換えることを忘れないでください。インテグレーション設定タブから見つけてください。

Copying your Integration token from the Configuration tab in the developer portal

トランスポートオプション

Notion MCP サーバーは、2 つのトランスポートモードをサポートしています。

STDIO トランスポート (デフォルト)

デフォルトのトランスポートモードは、通信に標準入出力を使用します。これは、Claude Desktop などのほとんどのクライアントで使用される標準的な MCP トランスポートです。

# Run with default stdio transport
npx @notionhq/notion-mcp-server

# Or explicitly specify stdio
npx @notionhq/notion-mcp-server --transport stdio

ストリーミング可能 HTTP トランスポート

Web ベースのアプリケーションや HTTP 通信を好むクライアント向けに、ストリーミング可能 HTTP トランスポートを使用できます。

# Run with Streamable HTTP transport on port 3000 (default)
npx @notionhq/notion-mcp-server --transport http

# Run on a custom port
npx @notionhq/notion-mcp-server --transport http --port 8080

# Bind to a different host. The default is 127.0.0.1.
npx @notionhq/notion-mcp-server --transport http --host 0.0.0.0

# Run with a custom authentication token
npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

ストリーミング可能 HTTP トランスポートを使用する場合、サーバーはデフォルトで http://127.0.0.1:<port>/mcp で利用可能になります。

認証

ストリーミング可能 HTTP トランスポートでは、セキュリティのためにベアラートークン認証が必要です。3 つのオプションがあります。

オプション 1: 自動生成トークン (開発専用)

npx @notionhq/notion-mcp-server --transport http

サーバーは安全なランダムトークンを生成し、制限された権限でファイルに書き込みます。

Generated auth token written to: /tmp/.notion-mcp-auth-token-12345

オプション 2: コマンドラインによるカスタムトークン (本番環境で推奨)

npx @notionhq/notion-mcp-server --transport http --auth-token "your-secret-token"

オプション 3: 環境変数によるカスタムトークン (本番環境で推奨)

AUTH_TOKEN="your-secret-token" npx @notionhq/notion-mcp-server --transport http

コマンドライン引数 --auth-token は、AUTH_TOKEN 環境変数よりも優先されます（両方が提供された場合）。

安全でないオプション: HTTP 認証の無効化

明示的な安全でないフラグを使用してのみ、ベアラートークン認証を無効にできます。

npx @notionhq/notion-mcp-server --transport http --unsafe-disable-auth

警告: --unsafe-disable-auth は安全ではありません。DNS リバインディングを介して、アクセスしたページからサーバーに到達可能になる可能性があります。隔離されたネットワークでのみ使用してください。

認証が無効になっている場合、サーバーは Host ヘッダーと Origin ヘッダーを設定されたローカルホストおよびループバックホストと照合することで、DNS リバインディング保護を有効にします。以前の --disable-auth フラグは非推奨のエイリアスとして引き続き受け入れられますが、警告が表示されます。

HTTP リクエストの作成

ストリーミング可能 HTTP トランスポートへのすべてのリクエストには、Authorization ヘッダーにベアラートークンを含める必要があります。

# Example request
curl -H "Authorization: Bearer your-token-here" \
     -H "Content-Type: application/json" \
     -H "mcp-session-id: your-session-id" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

注: どちらのトランスポートモードを使用する場合でも、NOTION_TOKEN 環境変数 (推奨) または OPENAPI_MCP_HEADERS 環境変数のいずれかを Notion インテグレーショントークンで設定してください。

複数のインテグレーションの提供 (リクエストごとのトークンパススルー)

デフォルトでは、サーバーは起動時に組み込まれた単一のトークンで Notion に対して認証するため、1 つのデプロイメントが 1 つの Notion インテグレーションに固定されます。単一のデプロイメントで複数のインテグレーションを提供できるようにするには、トークンパススルーを有効にして、各クライアントが接続ごとに独自の Notion インテグレーショントークンを提供できるようにします。

# Enable per-request Notion tokens (flag or ENABLE_TOKEN_PASSTHROUGH=true)
npx @notionhq/notion-mcp-server --transport http --enable-token-passthrough

クライアントは、専用の Notion-Token ヘッダーを使用して、initialize リクエストで Notion トークンを送信します。

curl -H "Authorization: Bearer <server-auth-token>" \
     -H "Notion-Token: ntn_****" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc": "2.0", "method": "initialize", "params": {}, "id": 1}' \
     http://localhost:3000/mcp

接続ごとのトークンの解決方法 (順序):

Notion-Token ヘッダー (推奨 — 明確であり、サーバー自身の Authorization ゲートウェイ認証と共存できます)。存在する場合、有効な Notion トークンである必要があり、そうでない場合、リクエストは 401 で拒否されます。
Authorization: Bearer ntn_**** — サーバー自身のベアラー認証がオフになっている場合 (--unsafe-disable-auth) のみ、ヘッダーが Notion トークンを直接運ぶことができます。
それ以外の場合は、起動時の環境変数トークン (NOTION_TOKEN / OPENAPI_MCP_HEADERS) が設定されていれば使用されるため、パススルーとデフォルトのインテグレーションを 1 つのデプロイメントで共存させることができます。

注:

Notion トークンプレフィックス (ntn_、レガシー secret_) を持つ値のみが Notion トークンとして扱われるため、サーバーのゲートウェイシークレットとテナントの Notion トークンが衝突することはありません。
各トークンは MCP セッションにバインドされます。トークンがログに記録されることはありません (編集されたプレフィックスのみが出力されます)。
これは意図的なトークンパススルー設定です。常に TLS 経由でデプロイし、マルチテナントトラフィックの前にゲートウェイとしてサーバー自身のベアラー認証 (--auth-token) を有効にしておくことを推奨します。

例

次の指示を使用する

Comment "Hello MCP" on page "Getting started"

AI は、タスクを達成するために 2 つの API 呼び出し、v1/search と v1/comments を正しく計画します。

同様に、次の指示により、「Notion MCP」という名前の新しいページが親ページ「Development」に追加されます。

Add a page titled "Notion MCP" to page "Development"

コンテンツ ID を直接参照することもできます。

Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2

開発

ビルドとテスト

npm run build
npm test

実行

npx -y --prefix /path/to/local/notion-mcp-server @notionhq/notion-mcp-server

Cursor で変更をローカルでテストする:

リポジトリルートから npm link コマンドを実行して、notion-mcp-server パッケージへのマシングローバルなシンボリックリンクを作成します。
以下の設定スニペットを Cursor の mcp.json (またはテストしたい他の MCP クライアント) にマージします。
(クリーンアップ) リポジトリルートから npm unlink を実行します。

{
  "mcpServers": {
    "notion-local-package": {
      "command": "notion-mcp-server",
      "env": {
        "NOTION_TOKEN": "ntn_..."
      }
    }
  }
}

公開

npm login
npm publish --access public