Notion MCPサーバーの使い方 — Claude Codeへの接続手順とコネクタとの違い

Notionは、Claude CodeのようなMCPクライアントから直接つなげるMCPサーバーをhttps://mcp.notion.com/mcpで公式提供しています。ローカルにサーバーを立てる必要はなく、claude mcp addの1行とOAuth認証だけで、ワークスペースの検索・作成・更新をClaude Codeのセッションから任せられます。似た名前の仕組みにclaude.aiの「Notionコネクタ」がありますが、こちらはclaude.aiのConnectorsから接続する別の経路です。この記事はClaude Code側のMCP接続に絞り、v2.1.285で実際に出力を確認した手順、プランで挙動が変わる検索、つまずきやすい点を扱います。MCP自体の仕組みはMCPとは — AIと外部ツールをつなぐ標準プロトコルが対応します。

Claude CodeとNotionを連携する最短の手順は、次のコマンドを実行し、Claude Code内で/mcpを開いて認証するだけです。

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

Notion MCPサーバーとは — mcp.notion.comへのリモート接続

Notion MCPサーバーはNotionがホストするリモートMCPサーバーです。OAuthで認証すると、MCPクライアントは接続したアカウントがアクセスできる範囲でNotionのコンテンツを読み書きできます。Codex・Cursor・VS Code・Claude Codeなど、複数のクライアントの接続手順がNotion自身のドキュメントに載っています。

エンドポイントは2つあります。推奨はStreamable HTTPのhttps://mcp.notion.com/mcpで、https://mcp.notion.com/sseはクライアントがStreamable HTTPに未対応のときだけ使うフォールバックです。リモート接続自体に非対応で、ローカルのstdioサーバーしか受け付けないクライアントには、mcp-remoteを挟む構成が案内されています。

ローカルで動かすオープンソース版(notion-mcp-server)は、Notionが積極的なメンテナンスは終えたと説明しています。ベアラートークン認証と旧来のv1 APIが使えるので、対話的なOAuthを通せない自動化では残る選択肢ですが、接続とデプロイは自分で管理することになります。対話的に使うなら、mcp.notion.comが第一選択です。

Claude CodeでNotion MCPサーバーに接続する手順

スコープは--scopeで切り替えます。既定のlocalは今のプロジェクトの自分だけ、userは全プロジェクト共通、projectはチームで共有する設定です。スコープごとの細かい挙動はClaude Code MCP設定ガイドにまとめています。

実機で確認した.mcp.jsonと承認待ちの表示

--scope projectは挙動に注意が要ります。空のディレクトリで実行し、書き出された.mcp.jsonとclaude mcp getの出力を確かめました(v2.1.285、認証やネットワーク接続は行っていません)。

claude mcp add --transport http --scope project notion https://mcp.notion.com/mcp
cat .mcp.json
claude mcp get notion

.mcp.jsonは次の内容でした。

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

claude mcp get notionの出力は次のとおりです。

notion:
  Scope: Project config (shared via .mcp.json)
  Status: ⏸ Pending approval (run `claude` to approve)
  Type: http
  URL: https://mcp.notion.com/mcp

書き出されるのはURLと接続方式だけで、トークンは含まれません。そのためコミットしてチームで共有できます。ただし追加した本人も含め、claudeを対話的に起動して承認するまではPending approvalのままで、接続もヘルスチェックも行われません。承認の選択をやり直したいときはclaude mcp reset-project-choicesを使います。

接続後に使える主要ツール

Notion MCPサーバーには20種類を超えるツールがあり、中心は次の5系統です。ページの作成・更新はallow_asyncという引数で非同期にでき、その使い方は後の節で説明します。

複数のツールを組み合わせて呼べるので、「関連ページを検索して、その内容をまとめた新規ページを作る」といった依頼も、検索と作成を順に呼んで完結します。URLからの添付は、ダウンロードが1分以内に終わることや、リダイレクトや認証ヘッダーが不要なことが条件です。サイズの上限は無料ワークスペースで5MiB、有料で50MiBです。

検索の挙動はプランと接続で変わる

notion-searchはどのプランでも使えますが、AI検索が使える接続では、キーワードだけの検索がAI検索に切り替わります。結果のtypeがai_searchになり、Notionと接続済み外部ソースをまとめた結果が返ります。フィルターを指定した検索、クエリが空の検索、関連度以外の並べ替えは、従来のワークスペース検索(workspace_search)のままです。

プランに含まれないフィルターや並べ替えを指定しても、呼び出しは失敗しません。使えない項目だけが捨てられ、残りの条件で検索が走り、noticesに捨てた項目名が入ります。結果が意図より広くなるのは、この仕様が原因です。次の項目にはBusinessまたはEnterpriseのFull Notion MCPが必要です。

• 更新者(editor)での絞り込み
• 最終更新日での絞り込み
• 複数チームスペースにまたがる絞り込み
• タイトルのみを対象にした検索
• コンテンツステータスでの絞り込み
• 日付順の並べ替え

単一のチームスペースでの絞り込みは全プランで使えます。無料プランで動かないのか設定ミスなのか迷うときは、notion-get-tool-accessを呼びます。{}を渡すと全ツールのcurrent_tool_accessが返り、tool_namesで絞ることもできます。各ツールのstatusはavailable・available_with_limit・plan_required・upgrade_required・full_version_required・not_enabledのどれかで、制限された引数はrestricted_parametersに理由つきで並びます。なおnotion-get-usersにselfを渡すと、接続中のユーザー自身の情報が取れます。

検索とデータソースの問い合わせには、ツール固有のレート制限もあります。notion-searchとnotion-query-data-sourcesはどちらも10秒に20回までです。待ち時間が2秒以内なら一度だけ自動で再試行され、それより長いとcode: "rate_limited"のツールエラーがすぐ返ります。並列検索を増やして詰まったときは、並列数を減らすよう依頼し直します。

書き込みを非同期にするallow_async

notion-create-pagesとnotion-update-pageは、allow_async: trueで非同期実行にできます。これはアシスタント向けの推奨で、省略した場合の意味は従来と同じです。ただし省略しても、同期の待ち時間を超えるとasync_taskが返ることがあります。どちらの形も扱えるようにしておきます。応答にasync_taskが返ったら、そのidをtask_idとしてnotion-get-async-taskを呼び、succeededかfailedになるまで確認します。次の作業がそのページに依存するなら、succeededを待ってから進める必要があります。

{
  "tool": "notion-create-pages",
  "arguments": {
    "allow_async": true,
    "parent": { "page_id": "YOUR_PAGE_ID" },
    "pages": [{ "properties": { "title": "Migration plan" }, "content": "# Migration plan" }]
  }
}

キューに載せるには大きすぎる書き込みは、async_taskではなくvalidation_errorで返ります。ページを分けるか、allow_async: falseで同期実行に切り替えます。succeededが保証するのはページの書き込みまでで、テンプレートの適用完了までは含みません。テンプレートを使う場合は、内容が揃ったかをプロパティや本文で別に確かめます。

Notion Skillsをこの接続から呼び出す・作る

Notion MCPサーバーには「Notion Skills」という独自の仕組みがあります。繰り返す作業の手順をNotionのページに書いておき、それをワークフローの定義として再利用する機能です。

作成はnotion-create-pagesにis_skill: trueを付けます。既存ページはそのままnotion-convert-page-to-skillでSkill化でき、実行には編集権限が必要です。呼び出す側は、Skillの正確なURLをnotion-fetchに渡して内容を読みます。書き方の指針は、notion://docs/skillsというMCPリソースにあります。

取得したページを指示として扱うのは、ユーザーの依頼がそのSkillや手順を求めているときだけです。Skillの中身を見たい・要約したい・編集したいという依頼では、ページは単なる内容として扱われます。notion-download-skillはSKILL.mdと補助ファイルをtar.gzごと取得します。補助ファイルが無いSkillでもアーカイブが返り、URLの有効期限は1時間です。ワークスペースでSkills APIが有効なことが条件で、評価モードやワークスペース所有のMCP接続では使えません。ダウンロードしても、Skillやスクリプトは実行されません。

Notion公式のClaude Codeプラグインでまとめて導入する

Notionは、MCPサーバーとSkills・スラッシュコマンドを1つにまとめたClaude Code用プラグインを、公式リポジトリ(makenotion/claude-code-notion-plugin)で配布しています。個別にclaude mcp addを打つ代わりに、次の2行で導入できます。

/plugin marketplace add makenotion/claude-code-notion-plugin
/plugin install notion-workspace-plugin@notion-plugin-marketplace

同梱されるのは、4つのSkillsです。名前は「Knowledge Capture」「Meeting Intelligence」「Research Documentation」「Spec to Implementation」です。加えて/Notion:searchや/Notion:create-task、/Notion:database-queryといったスラッシュコマンドも入ります。議事録の構造化やタスク化のような具体的な使い方が、最初からコマンドとして組まれています。導入後はClaude Codeの再起動が必要で、認証はMCPサーバー単体の接続と同じくOAuthです。

セキュリティで気をつけること — 権限範囲とプロンプトインジェクション

Notion MCPサーバーが使える範囲は、接続したアカウント自身のNotion権限と同じです。接続したクライアントは、自分がアクセスできる内容すべてに触れられます。業務用の広い権限を持つアカウントで、無条件に接続するのは避けたいところです。Notionのヘルプも、個人のAIアプリをつなぐ1人用の使い方から始めることを勧めています。

もう1つは、間接的なプロンプトインジェクションです。ツールが返す検索結果やページ本文に、悪意のある指示が紛れている可能性があります。Claudeがそれに従うと、意図しないデータの開示や書き換えにつながります。しかも接続したクライアントは、Notionから受け取った内容をNotionの外の別システムへ送れます。

ワークスペース側の制御は、Settings→Connectionsにあります。ワークスペースオーナーは接続中のMCPクライアントを管理でき、組織オーナーはAdmin APIで接続の一覧取得と取り消しもできます。Enterpriseプランでは、承認済みのAIアプリだけに絞れます。Permissionsタブで「Restrict AI apps members can connect」を「Only from approved list」にします。

この承認リストには癖があります。設定した時点で接続済みのAIアプリは、自動で承認リストに入ります。リストから外しても既存トークンは取り消せないため、接続一覧には残りますが、Notionは承認外のアプリからの呼び出しをすべて遮断します。特定のアプリだけを切り離す手段はなく、「Disconnect All Users」で全接続を切って、承認済みのアプリから再接続してもらうのが現状の回避策です。Oktaを使う組織では、管理者が1度設定するだけでメンバーが個別に承認しなくて済む「エンタープライズ管理接続」もあります。

Notion MCPサーバーとNotionコネクタはどう違うか

同じNotion連携でも、設定の作り方が2つあります。

どちらも最終的にはNotion経由でワークスペースへアクセスします。プロジェクトごとに接続を切り替えたいならMCPサーバー、アカウント全体で1つの接続を使い回したいならコネクタが向いています。コネクタ側の設定はClaude Notion連携の設定方法とできること、Coworkの自動実行タスクへの組み込みはCowork Notion連携でワークスペースを検索・更新するで扱っています。MCPのOAuth実装そのものの仕組みはリモートMCPのOAuth認証が対応します。

よくあるつまずき

• Pending approvalのまま動かない: --scope projectで追加した.mcp.jsonの承認が済んでいません。claudeを対話的に起動して承認します
• 認証が通らない・古い認証が残る: /mcpのサーバーメニューにある「Clear authentication」でトークンを消し、認証をやり直します。Notionの案内も、切断と再接続、それに対象ワークスペースでの自分の権限の確認です
• 「共有していません」と返る: 見えるのは、接続したアカウントがアクセスできる範囲だけです。対象のページがそのアカウントと共有されているかを確認します
• 検索の絞り込みが効かない: 更新者や複数チームスペースをまたぐ絞り込みは、Business以上のFull Notion MCPが前提です。noticesの内容かnotion-get-tool-accessの結果を見ます
• 自動化から使えない: 接続には対話的なOAuthが必須で、非対話的な認可は「対応を進めている」段階です。時期は明らかにされていません

最後の制約には補足があります。Notionが載せているDevin向けの手順では、Notionのサービスアカウントで組織共有の接続を作り、権限を持つ人が1度だけOAuthを完了させる構成が案内されています。ただしこれはDevin側の機能を前提にした手順で、Claude Codeで同じことができるとは書かれていません。cronなどでの定期実行は、この制約を先に確認したうえで設計します。

まとめ

Claude Codeでは、claude mcp add --transport http notion https://mcp.notion.com/mcpと/mcpでのOAuth認証で使い始められます。チームで共有するなら--scope projectの承認手順まで含めて設計し、書き込み系は実行前の確認を挟む運用を前提にしておくと安全です。