Notion MCP Server

Notion MCP サーバー

メモ

最適なエクスペリエンスを得るには、公式ホスト型 MCP サーバーの Remote Notion MCP をご利用ください。 このリポジトリは、現在積極的なメンテナンスやサポートを終了している、別個のセルフホスト型 MCP サーバー実装です。代わりに Remote Notion MCP をご利用ください。 AI エージェントに特化して構築されており、 はるかに少ないトークンで、より速く結果を得られます。

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

機能	Remote Notion MCP	このプロジェクト（ローカル）
高速なホスト型エクスペリエンス	✅	ローカルでの実行と更新
トークン効率の高い応答	✅	限定的
AI エージェントに特化した強力なツール	✅	API 由来の基本的なツール
Notion ワークスペース全体の意味検索	✅	キーワード検索のみ
接続済みアプリを対象とした AI Connector 検索	✅	利用不可
Markdown ネイティブなページの読み取りと編集	✅	2 つのページコンテンツツールのみ
シームレスな OAuth 設定	✅	手動でのトークンと JSON 設定
各ユーザーの既存の Notion 権限を尊重	✅	手動でのインテグレーション権限とページ共有
積極的なサポートと継続的な改善	✅	積極的なサポートなし

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

現在、Remote Notion MCP を優先し、こちらのみを積極的にサポートしています。そのため、以下の点にご留意ください。

• 将来的に、このローカル MCP サーバーのリポジトリを終了する可能性があります。
• こちらのイシューとプルリクエストは、積極的に確認していません。
• リモート MCP に関するイシューはここに投稿しないでください。代わりに Notion サポートまでお問い合わせください。

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

---

⚠️ バージョン 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 にアクセスし、新しい内部インテグレーションを作成するか、既存のものを選択します。

公開する 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

WARNING: --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

Note: いずれのトランスポートモードを使用する場合でも、NOTION_TOKEN 環境変数（推奨）または OPENAPI_MCP_HEADERS 環境変数に Notion 統合トークンを設定してください。

複数の連携機能を提供する（リクエストごとのトークンパススルー）

デフォルトでは、サーバーは起動時に設定された単一のトークンを使って Notion に認証するため、1つのデプロイメントで利用できる Notion 連携機能は1つに限られます。1つのデプロイメントで複数の連携機能を提供するには、トークンパススルーを有効にし、各クライアントが接続ごとに独自の 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