Claude Code×Notion連携の設定と活用手順【2026】

関連記事Claude Code（クロードコード）とは？できること・料金・使い方を初心者にもやさしく解説【2026年版】 ／ Claude Code 使用量を完全制御する実装ガイド【2026年版】 ／ Claude Code ログイン方法・できない時の対処法｜2026年版ガイド

Claude CodeとNotionを連携するには？

Claude CodeとNotionは、NotionのMCP（Model Context Protocol）サーバーをClaude Codeに登録することで連携できます。登録すると、Claude CodeからNotionのページやデータベースを読み書きでき、「議事録をNotionに起こす」「仕様をNotionから読んで実装する」といった操作を対話の流れの中で行えます。

• MCP経由で繋ぐのが標準： Notion連携はMCPサーバーとして追加します。claude mcp add で登録するか、プロジェクトのMCP設定ファイルにサーバーを記述します。
• 接続確認は /mcp： 追加後、セッション中に /mcp を実行すると、Notionサーバーが正しく接続できているか（認証が通っているか）を確認できます。
• 認証を先に通す： Notion側でインテグレーション用のトークン（またはOAuth連携）を用意し、対象のページ/DBにそのインテグレーションのアクセス権を付与しておく必要があります。権限を渡していないページは読み書きできません。
• 範囲を絞る： 連携先を広げすぎると意図しない書き込みのリスクが増えます。最初は必要なDB/ページだけに権限を絞るのが安全です。

Claude CodeとNotionを連携させる方法と実践ガイド

Claude CodeからNotionのデータを読み書きしたい、コーディング作業とナレッジベースをシームレスにつなげたい——そう考えている開発者やエンジニアが増えています。Claude Codeは強力なAIコーディングエージェントですが、単体で使うだけでなくNotion APIと組み合わせることで、ドキュメント管理・タスク管理・ナレッジベースへのアクセスを自動化できます。本記事では、連携の仕組みから具体的なセットアップ手順、実用的なユースケース、運用上のコツまでを網羅的に解説します。クリスタルメソッドでもClaude Codeを実務で日常利用しており、その知見を踏まえた実践的な内容をお届けします。

Claude CodeとNotionを連携する「仕組み」を理解する

連携の全体像を把握しておくことで、設定時のつまずきを大幅に減らせます。Claude CodeとNotionをつなぐ主なルートは3つあります。

開発者が最も恩恵を受けやすいのはMCP経由の連携です。Claude Code内でコーディング中にそのままNotionページを参照・更新できるため、ツールの行き来が不要になります。以下ではMCP経由の方法を中心に、Notion API直接利用のアプローチも詳しく解説します。

前提知識：Claude CodeのMCPとは

MCP（Model Context Protocol）はAnthropicが策定したオープンプロトコルで、Claude Codeが外部ツール・データソースを「ツール」として呼び出せる仕組みです。MCPサーバーを追加することで、ファイルシステム、データベース、外部APIなどをClaude Codeのコンテキストに取り込めます。

MCPサーバーには、手元のパソコンで動かすもの（ローカル）と、提供元がインターネット上で動かしているもの（リモート）があります。Claude Codeでは claude mcp add コマンドで登録し、登録内容は使う範囲（スコープ）に応じて、自分だけが使う場合は ~/.claude.json、チームで共有する場合はプロジェクト直下の .mcp.json に保存されます（.claude/settings.json や、デスクトップアプリ用の claude_desktop_config.json ではありません）。Notionの場合は、Notionが公式に提供しているリモートMCPサーバー（https://mcp.notion.com/mcp）を使うのが現在の標準です。

ステップ1：Notion APIのインテグレーションを作成する

Notion公式のリモートMCPサーバーで連携する場合（ステップ2）は、この手順は不要です。ブラウザでNotionにログインして許可するだけ（OAuth認証）でつながるためです。インテグレーションを作成してAPIトークンを取得する必要があるのは、ステップ3の「Notion APIをスクリプトから直接使う方法」と、自分でMCPサーバーを動かす旧方式の場合です。

1. Notion Developers（developers.notion.com）にアクセスし、Notionアカウントでログインする
2. 「My integrations」→「New integration」をクリック
3. インテグレーション名（例：claude-code-connector）を入力し、対象のワークスペースを選択する
4. Capabilitiesで必要な権限を設定する。一般的には以下が必要：
   • Read content（ページ・DBの読み取り）
   • Update content（ページ・DBの更新）
   • Insert content（新規ページ・ブロックの追加）
5. 「Submit」をクリックし、表示されたInternal Integration Token（ntn_ で始まる文字列。以前に発行したものは secret_ で始まります）を安全な場所にコピーしておく

次に、アクセスしたいNotionページまたはデータベースにインテグレーションを接続します。Notionの対象ページ右上「…」→「Connections」→作成したインテグレーションを追加することで、APIからそのページへのアクセスが許可されます。この手順を忘れると「object not found」エラーが返ります。実務でも最初はここでつまずくことが多いため、連携したいページすべてにインテグレーションが追加されているか必ず確認してください。

ステップ2：MCP経由でNotion連携を設定する（推奨方法）

Notionとつなぐ手順は、次の3つです。Node.jsのインストールやAPIトークンの発行は要りません（Notion公式ドキュメント「Connect to Notion MCP」の手順。2026年10月10日確認）。

1. ターミナルでサーバーを登録する

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

2. Claude Codeを起動して認証する：claude を起動し、/mcp を実行してNotionを選び、ブラウザに表示される画面でNotionにログインして接続を許可します。
3. 動かして確かめる：「Notionで『議事録』を検索して」のように頼み、Notionの内容が返ってくれば完了です。

登録先は --scope で選べます。指定しない場合は local（今のプロジェクトで自分だけが使う）、--scope project はプロジェクト直下の .mcp.json に書き出してチームで共有、--scope user は自分のすべてのプロジェクトで使える設定です。接続後は、認証したNotionアカウントが見られる範囲のページを読み書きできます。

現在はNotionが公式のリモートMCPサーバー（https://mcp.notion.com/mcp）を提供しており、Claude Code側は1行のコマンドで追加できます。下は、テスト用のフォルダで claude mcp add --transport http --scope project notion https://mcp.notion.com/mcp を実行し、claude mcp get notion で確認した実際の画面です（2026年10月5日、Claude Code v2.1.289で撮影）。設定はプロジェクトの .mcp.json に登録され、次に claude を起動したときに承認すると使えるようになります（Notionアカウントでの認証はその後に行います）。画面の一部（サーバーのユーザー名）は伏せています。

Notion公式プラグインでまとめて入れる方法

Notionは、Claude Code用の公式プラグイン（makenotion/claude-code-notion-plugin）も公開しています。上と同じリモートMCPサーバーに加えて、Notionでの作業のしかたをClaudeに教えるSkills（Knowledge Capture・Meeting Intelligence・Research Documentation・Spec to Implementation の4つ）と、/Notion:search（ワークスペースを検索）・/Notion:create-task（タスクを作成）・/Notion:database-query（データベースを検索）などのスラッシュコマンドが一度に入ります。Claude Codeの中で次の2つを実行し、Claude Codeを再起動します。

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

Notion MCPで使える主なツール

接続すると、Claude Codeは次のようなツールを状況に応じて呼び出します（Notion公式ドキュメント「Supported tools」より抜粋）。利用者がツール名を覚える必要はなく、ふだんの言葉で頼めば足ります。

※ ツールの種類や名前はNotion側の更新で変わります。使えるツールは /mcp で確認できます。

（参考）自分でMCPサーバーを動かす旧方式

この方式に必要なものは次のとおりです。

• Node.js 18以上（node -vで確認）
• Claude Code（最新版）
• ステップ1で取得したNotionインテグレーショントークン

設定ファイルへの記述

プロジェクト直下の .mcp.json に以下を記述します（公式ドキュメントが示すMCPサーバーの保存先は .mcp.json と ~/.claude.json で、.claude/settings.json ではありません）。書き方はNotion公式リポジトリのREADMEにある設定例と同じです。

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_あなたのトークン"
      }
    }
  }
}

セキュリティ上の注意：トークンを直接設定ファイルに書く場合は、そのファイルを.gitignoreに追加し、リポジトリに含めないようにしてください。環境変数（.envファイル）経由で渡す方法も有効です。クリスタルメソッドの実運用では、.envにトークンを置き、direnvで自動ロードする構成にしています。

動作確認

どちらの方式でも、設定後にClaude Codeを起動し直して、次のように頼んでみます。

「Notionの[データベース名]の内容を取得して一覧にして」

ツールの呼び出し（リモートMCPサーバーなら notion-search や notion-fetch など）が表示され、Notionのデータが返ってくれば連携成功です。ターミナルで claude mcp get notion を実行すると、サーバーの接続状態を確認できます。

ステップ3：Notion API＋Pythonスクリプトで連携する方法

MCPを使わず、Claude Codeにスクリプトを生成・実行させる方法も実用的です。特に、既存のPythonプロジェクトにNotion連携を組み込みたい場合や、複雑なデータ加工が必要な場合に向いています。

notion-clientのインストール

pip install notion-client

基本的な読み取りスクリプト例

Claude Codeに「このデータベースIDのNotionデータベースを取得してDataFrameにするPythonスクリプトを書いて」と指示すると、以下のようなコードを生成・実行できます。

import os
from notion_client import Client
import pandas as pd

notion = Client(auth=os.environ["NOTION_TOKEN"])

def query_database(database_id: str) -> pd.DataFrame:
    results = []
    has_more = True
    start_cursor = None

    while has_more:
        response = notion.databases.query(
            database_id=database_id,
            start_cursor=start_cursor
        )
        results.extend(response["results"])
        has_more = response["has_more"]
        start_cursor = response.get("next_cursor")

    rows = []
    for page in results:
        props = page["properties"]
        row = {}
        for key, value in props.items():
            prop_type = value["type"]
            if prop_type == "title":
                row[key] = value["title"][0]["plain_text"] if value["title"] else ""
            elif prop_type == "rich_text":
                row[key] = value["rich_text"][0]["plain_text"] if value["rich_text"] else ""
            elif prop_type == "select":
                row[key] = value["select"]["name"] if value["select"] else ""
            elif prop_type == "number":
                row[key] = value["number"]
            elif prop_type == "date":
                row[key] = value["date"]["start"] if value["date"] else ""
        rows.append(row)

    return pd.DataFrame(rows)

# 使用例
df = query_database("あなたのデータベースID")
print(df.head())

データベースIDはNotionのURL（notion.so/ワークスペース名/32文字のID?v=…）から取得できます。v=の前の部分がデータベースIDです。

ページへの書き込み例

def create_page(database_id: str, title: str, status: str, note: str) -> dict:
    return notion.pages.create(
        parent={"database_id": database_id},
        properties={
            "Name": {
                "title": [{"text": {"content": title}}]
            },
            "Status": {
                "select": {"name": status}
            },
            "Note": {
                "rich_text": [{"text": {"content": note}}]
            }
        }
    )

Claude Codeはこうしたスクリプトをその場で生成・実行できるため、「今日の日付でタスクページを追加して」のような自然言語指示からNotionへの書き込みが可能になります。

実践ユースケース：どんな作業が自動化できるか

連携が完成すると、開発作業の中で以下のような活用が現実的になります。クリスタルメソッドの実運用でも活用しているものを含めて紹介します。

ユースケース1：仕様書・設計ドキュメントをリアルタイム参照しながらコーディング

Notionに書かれた仕様書やAPIドキュメントをClaude Codeのコンテキストに取り込み、「仕様書に基づいてこのエンドポイントを実装して」と指示できます。わざわざNotionとエディタを行き来する必要がなくなり、実装と仕様の乖離を防ぎやすくなります。

ユースケース2：タスク・バグトラッカーへの自動起票

コードレビュー中に発見したバグや改善点を「このエラーをNotionのバグトラッカーDBに起票して」と一言指示するだけで、ページが自動生成されます。ステータス・優先度・担当者などのプロパティも指示に含めれば一括設定できます。

ユースケース3：ミーティングメモ・議事録の構造化保存

会議後にまとめた箇条書きのメモをClaude Codeに渡し、「このメモをNotionの議事録テンプレートに従って整形してページ追加して」と指示することで、構造化されたメモが自動保存されます。

ユースケース4：コードとドキュメントの同期

関数やモジュールのREADMEを更新した際に「この変更をNotionの開発者向けドキュメントページにも反映して」と指示すれば、コードとNotionドキュメントを同期できます。ドキュメントが陳腐化しやすい課題への実践的な解決策です。

ユースケース5：プロジェクト進捗の集計・ダッシュボード更新

GitHubのコミット情報や完了タスクの集計結果をNotionのプロジェクト管理DBに定期書き込みするスクリプトをClaude Codeで生成・保守できます。cronやGitHub Actionsと組み合わせることで完全自動化が可能です。

よくあるエラーと対処法

実運用で遭遇しやすいエラーと対処法をまとめます。

「Could not find database with ID」エラー

データベースIDが間違っているか、インテグレーションがそのページに接続されていないケースがほぼすべてです。NotionページでConnections設定を確認し、インテグレーションが追加されているかチェックしてください。IDはハイフンなしの32文字で指定する場合もあります。

「Unauthorized」「403 Forbidden」エラー

トークンが無効またはインテグレーションに必要な権限（Read/Write）が付与されていない場合です。Notion DevelopersでインテグレーションのCapabilitiesを確認・更新してください。

MCPサーバーが認識されない

まず claude mcp list または claude mcp get notion で状態を確認します。プロジェクトの .mcp.json に登録したサーバーは、claude を起動して承認するまで「Pending approval（承認待ち）」と表示され、使えません。リモートMCPサーバーの場合は /mcp での認証が済んでいるかも確認してください。旧方式では、設定ファイルのJSONが壊れている（カンマ抜け・括弧の不一致）か、設定変更後にClaude Codeを起動し直していないケースが多いです。詳しいログは claude --debug で確認できます。

Notionのレート制限（429エラー）

Notion APIには接続ごとの利用回数の上限があり、公式リファレンスでは1分あたり180リクエスト（平均で1秒あたり3回）、BusinessプランとEnterpriseプランは1分あたり600リクエストとされています（2026年10月10日確認。上限は変わることがあります）。上限を超えるとHTTP 429が返り、Retry-After で待ち時間が示されます。MCP経由のツール呼び出しも同じ上限に数えられます。大量のページを一括処理する場合は、リクエスト間にtime.sleep(0.4)程度のウェイトを入れてください。Claude Codeに「rate limitを考慮したスクリプトにして」と指示すれば自動で対応コードを生成します。

ページのブロックコンテンツが取得できない

databases.queryはプロパティのみ返します。ページ本文（ブロック）を取得するにはblocks.children.list(block_id=page_id)を別途呼ぶ必要があります。

実運用で遭遇したレート制限・権限エラーの実体験

クリスタルメソッドでは代表の河合が1年以上、Claude CodeをCLAUDE.mdにNotionの参照情報を組み込んだ形で日常的に業務運用しています。その中で実際に遭遇したのが、Notion API側のレート制限（短時間に多数のページ・データベースへ連続アクセスした際に発生するエラー）と、インテグレーションに該当ページ・データベースへの権限（Connect）を明示的に与え忘れたまま接続しようとして起きる権限エラーです。

レート制限は、一度に大量のページを読み込ませる指示を出すのではなく、対象データベースやページを絞って段階的に依頼することで発生頻度を抑えられます。権限エラーは、Notion側で対象ページ・データベースを開き、右上の「接続」からインテグレーションを個別に許可しないと、API作成時点で有効化していても実際のアクセス時に弾かれる、という挙動が原因であることが多く、エラーメッセージだけでは気づきにくい点です。MCP経由・API直接利用のどちらの方式でも起こり得るため、上記いずれかのステップで似た事象に遭遇した場合は、まずNotion側の接続許可設定を確認することをおすすめします。

セキュリティと権限管理のベストプラクティス

NotionのAPIトークンはワークスペース全体へのアクセス権を持ちうるため、取り扱いには十分な注意が必要です。

• 最小権限の原則：インテグレーションに必要なCapabilitiesだけを付与する。書き込み不要な用途ならRead onlyにする
• 接続ページの限定：インテグレーションは手動で接続を許可したページ・DBにしかアクセスできない仕様。すべてのページに接続するのではなく、必要なページのみに留める
• トークンの環境変数化：コードや設定ファイルにトークンをハードコーディングせず、.envファイル＋python-dotenvやdirenvで管理する
• gitignoreの徹底：.envファイルおよびMCP設定ファイルを.gitignoreに追加し、誤ってGitHubに公開しないようにする
• 定期的なトークンローテーション：Notion DevelopersでIntegration Tokenは再生成できる。チームメンバーが退職した場合や漏洩疑いがある場合はすぐにローテーションする

Notion公式が挙げる注意点：プロンプトインジェクション

Notionの公式ドキュメント（Security best practices）は、MCPで連携するときの注意として次の点を挙げています。

• 公式の接続先だけを使う：https://mcp.notion.com/mcp（推奨）または https://mcp.notion.com/sse。第三者が配布する設定を入れる前に、接続先のURLを確かめます。
• 読み込んだ内容を信用しすぎない：Notionのページに「この指示に従え」といった悪意のある文章が紛れていると、AIがそれに従って情報を外へ出したり内容を書き換えたりするおそれがあります（プロンプトインジェクション）。ツールが返した内容は信頼できないものとして扱い、AIが提案した操作は承認する前に確認します。
• 内容を変える操作の前に確認を挟む：ページの作成・更新など、内容を変える操作は実行前に確認する設定にしておきます。
• 管理者は接続を管理できる：ワークスペースのオーナーは、Notionの「設定」→「接続」でMCPクライアントからのアクセスを管理できます。

ドキュメント連携を安全に運用するために（一次情報）

監修者・河合継はClaude Codeを3.5の時代から1年以上、外部サービスとの連携を含めて実務で運用してきました。Notionのような外部ツールと繋ぐとき、運用面で効いた点を補足します。

• 権限は必要な範囲だけに絞る。連携先に広い権限を渡すほど、できることも事故の範囲も広がります。読み取りだけで足りるなら書き込みは渡さない、といった最小権限の発想が安全でした。
• 自動更新は「確認を挟む」運用にする。ドキュメントを自動で書き換えられると便利ですが、意図しない上書きも起こりえます。重要な更新は人が一度確認する流れにしておくと、取り返しのつかない事故を防げます。
• 繋いだら一度、想定どおり動くか試す。設定が通っても期待どおりとは限りません。小さく一往復させて挙動を確かめてから、日常のワークフローに組み込むのが堅実でした。

Claude Code＋Notion連携をさらに発展させるアイデア

基本的な連携が安定したら、以下の発展的な活用も検討できます。

CLAUDE.mdにNotionの情報を組み込む

プロジェクトルートに置くCLAUDE.md（Claude Codeが常時参照するプロジェクト説明ファイル）に「Notionデータベースの構造・よく使うDB ID・操作のルール」を記述しておくと、毎回説明しなくても意図通りの操作が行われやすくなります。クリスタルメソッドでも、よく使うNotionのDB IDやプロパティ名をCLAUDE.mdに記載することで、指示の省略化と精度向上を実現しています。

Notionデータをベクトル検索で活用

NotionのページをエクスポートしてEmbedding化し、RAG（Retrieval-Augmented Generation）パイプラインに組み込むと、Claude Codeが「ナレッジベース全体を参照して答える」高度な利用が可能になります。

GitHub Actions + Notion連携の自動化

PRマージ時やデプロイ完了時にNotionの進捗DBを自動更新するGitHub Actionsワークフローを、Claude Codeで生成・管理できます。CI/CDとナレッジ管理を統合した開発フローが実現します。

複数ワークスペースの横断管理

複数のNotionワークスペースにアクセスが必要な場合は、旧方式であればインテグレーショントークンをワークスペースごとに作成し、別名のサーバーとして登録することで対応できます。

よくある質問

Q. Claude CodeとNotionを連携する方法は？
A. 主に3つあります。MCP（Model Context Protocol）経由、Notion API＋カスタムスクリプト、Zapier／Make等の中間連携です。もっとも手軽なのは、Notionが公式に提供するリモートMCPサーバー（https://mcp.notion.com/mcp）をClaude Codeに登録する方法です。

Q. MCP経由の連携で最初に必要な準備は何ですか？
A. ターミナルで claude mcp add –transport http notion https://mcp.notion.com/mcp を実行し、Claude Codeを起動して /mcp からNotionにログインして接続を許可します。Node.jsやAPIトークンの準備は不要です。

Q. NotionのAPIトークン（インテグレーション）は必要ですか？
A. Notion公式のリモートMCPサーバーを使う場合は不要です。ブラウザでの認証（OAuth）でつながります。トークンが必要なのは、Notion APIをスクリプトから直接使う場合と、オープンソース版のnotion-mcp-serverを自分で動かす場合です。

Q. notion-mcp-server（npxで動かす方式）は今も使えますか？
A. 使えますが、Notionの公式ドキュメントはこのオープンソース版を「現在は積極的に保守されていない」とし、ほとんどの場合はリモートMCPサーバーを使うよう案内しています。使う場合は、プロジェクト直下の .mcp.json の mcpServers に command:”npx”、args:[“-y”,”@notionhq/notion-mcp-server”]、env の NOTION_TOKEN にトークンを指定します。

Q. 連携できているかはどう確認しますか？
A. Claude Codeのセッション中に /mcp を実行して接続状態を確認するか、ターミナルで claude mcp get notion を実行します。そのうえで「Notionで◯◯を検索して」と頼み、notion-search などのツール呼び出しが表示されてデータが返ってくれば連携成功です。

Q. Notion公式のClaude Code用プラグインはありますか？
A. あります。makenotion/claude-code-notion-plugin で、リモートMCPサーバーに加えて、Notion向けのSkillsと /Notion:search などのスラッシュコマンドが一度に入ります。/plugin marketplace add makenotion/claude-code-notion-plugin のあと /plugin install notion-workspace-plugin@notion-plugin-marketplace を実行します。

Q. MCPを使わない連携方法はありますか？
A. Notion APIをPython（notion-clientライブラリ等）で直接呼び出すスクリプトをClaude Codeに生成・実行させる方法があります。既存のPythonプロジェクトへの組み込みや、複雑なデータ加工が必要な場合に向いています。

Q. よくあるエラーにはどんなものがありますか？
A. データベースIDの誤りやインテグレーション未接続による「Could not find database with ID」、トークン無効や権限不足による「Unauthorized」「403 Forbidden」、承認待ちや認証前で「MCPサーバーが認識されない」、利用回数の上限（1分あたり180リクエスト。BusinessとEnterpriseは600）を超えたときの429エラーなどがあります。

Q. セキュリティ面で気をつけることは何ですか？
A. 公式の接続先（mcp.notion.com）だけを使うこと、Notionから読み込んだ内容に紛れた指示にAIが従ってしまうプロンプトインジェクションに注意し、内容を変える操作は実行前に確認すること、トークンを使う方式では必要な権限とページだけに絞り、トークンを環境変数で管理してリポジトリに含めないことが大切です。

Q. 連携後にどんな作業を自動化できますか？
A. 仕様書を参照しながらのコーディング、バグ・タスクの自動起票、議事録の構造化保存、コードとドキュメントの同期、GitHubのコミット情報などを使った進捗集計・ダッシュボード更新などができます。

---

まとめ

Claude CodeとNotionの連携は、Notion公式のリモートMCPサーバーを使うことで最もシームレスに実現できます。セットアップは claude mcp add でサーバーを登録→/mcp でNotionにログインして許可→動作確認、という3ステップで完了します。Notion APIを直接叩くPythonスクリプトをClaude Codeに生成・実行させる方法も有効で、柔軟なデータ操作や既存プロジェクトへの組み込みに向いています。

活用場面は仕様書の参照・タスク自動起票・議事録保存・ドキュメント同期・進捗集計と幅広く、コーディング作業とナレッジ管理のサイロを取り除く効果があります。セキュリティ面では、公式の接続先だけを使うこと、内容を変える操作の前に確認を挟むこと、トークンを使う場合は環境変数化と最小権限の徹底が重要です。まずは小さなユースケース（例：バグを1件Notionに起票する）から試し、動作を確認しながら段階的に活用範囲を広げていくことをお勧めします。

関連記事

• Claude Codeとは
• Claude CodeのAPI料金
• Claude CodeとCodexの比較
• Claude CodeとCursorの比較
• Claude Code hooks（フック）の設定と活用