Notion MCP

npx add-mcp 'https://mcp.notion.com/mcp'

Notion MCP サーバー

[!NOTE]

最適な体験を得るには、公式ホスト型 MCP サーバーである Remote Notion MCP をご利用ください。このリポジトリは、独立したセルフホスト型 MCP サーバー実装であり、現在は積極的にメンテナンスやサポートが行われていません。代わりに Remote Notion MCP をご利用ください。 Remote Notion MCP は、AI エージェントがより少ないトークンでより高速な結果を得られるように特別に設計されています。

Remote Notion MCP は、ワークスペースや接続済みアプリを意味的に検索し、Markdown 形式でページの読み書きができ、最も関連性の高いコンテキストのみを返します。つまり、待ち時間の短縮、コンテキストウィンドウ使用量の削減、トークンコストの低減につながります。また、OAuth を使用し、各ユーザーの既存の Notion 権限を自動的に尊重します。API トークン、JSON 設定、手動でのページ共有、ローカルサーバーの維持は不要です。

機能	Remote Notion MCP	このプロジェクト（ローカル）
高速なホスト型エクスペリエンス	✅	ローカルで実行・更新
トークン効率の高い応答	✅	限定的
AI エージェント向けに調整された強力なツール	✅	基本的な API 由来のツール
Notion ワークスペース全体の意味的検索	✅	キーワード検索のみ
接続済みアプリを横断する AI コネクタ検索	✅	利用不可
Markdown ネイティブなページの読み書き	✅	2 つのページコンテンツツールに限定
シームレスな OAuth セットアップ	✅	手動トークンと JSON 設定
各ユーザーの既存の Notion 権限を尊重	✅	手動の統合権限とページ共有
アクティブなサポートと継続的な改善	✅	積極的なサポートなし

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

私たちは Remote Notion MCP を優先し、これに対してのみ積極的なサポートを提供しています。その結果：

• このローカル MCP サーバーリポジトリは、将来廃止される可能性があります。
• ここでの Issue やプルリクエストは積極的に監視されていません。
• リモート MCP に関する Issue はここに報告せず、代わりに Notion サポートにお問い合わせください。

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

---

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

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

変更内容

削除されたツール（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 にアクセスし、新しい内部インテグレーションを作成するか、既存のものを選択します。

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

たとえば、「Configuration」タブで「Read content」アクセスのみを許可することで、読み取り専用のインテグレーショントークンを作成できます：

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

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

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

または、個別にページアクセスを許可することもできます。対象のページにアクセスし、3 つのドットをクリックして、「Connect to integration」を選択する必要があります。

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_**** をインテグレーションシークレットに置き換えることを忘れないでください。インテグレーション設定タブで確認できます：

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

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

Streamable HTTP トランスポート

Web ベースのアプリケーションや HTTP 通信を好むクライアント向けに、Streamable 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"

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

認証

Streamable 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 リクエストの作成

Streamable 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 インテグレーショントークンを NOTION_TOKEN 環境変数（推奨）または OPENAPI_MCP_HEADERS 環境変数のいずれかに必ず設定してください。

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

デフォルトでは、サーバーは起動時に組み込まれた単一のトークンで 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

各接続のトークンの解決方法（優先順）：

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

注：

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

例

1. 次の指示を使用する場合

Comment "Hello MCP" on page "Getting started"

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

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

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

1. コンテンツ 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で変更をローカルにテストする手順:

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

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

公開

npm login
npm publish --access public