claude code notion 連携｜2026年版ガイド

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_desktop_config.jsonまたは.claude/settings.json）に記述することで有効化されます。NotionのMCPサーバーはAnthropicの公式リポジトリ、およびコミュニティが公開しているものを利用できます。

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

どの連携方式を選んでも、最初にNotionのInternal Integration（インテグレーション）を作成してAPIトークンを取得する必要があります。

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（secret_xxxx…形式）を安全な場所にコピーしておく

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

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

現時点でよく使われているのはnotion-mcp-server（Notionが公式に提供するMCPサーバーパッケージ）です。2024年末にNotion社がMCP対応の公式サーバーをリリースしており、Node.js環境があればnpxで手軽に動かせます。

必要な環境

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

設定ファイルへの記述

Claude Codeの設定ファイル（プロジェクトルートの.claude/settings.jsonまたはグローバル設定）に以下を追記します。

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": [
        "-y",
        "@notionhq/notion-mcp-server"
      ],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\": \"Bearer secret_あなたのトークン\", \"Notion-Version\": \"2022-06-28\"}"
      }
    }
  }
}

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

動作確認

設定後にClaude Codeを再起動し、Claude Codeのチャット欄で次のように試します：

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

ツールの呼び出しが表示され（notion_query_database等）、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サーバーが認識されない

設定ファイルのJSONが壊れている（カンマ抜け・括弧の不一致）か、Claude Codeを設定変更後に再起動していないケースが多いです。claude --mcp-debugオプションでMCPの動作ログを確認できます。

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

Notion APIは1秒あたり3リクエストの制限があります。大量のページを一括処理する場合は、リクエスト間にtime.sleep(0.4)程度のウェイトを入れてください。Claude Codeに「rate limitを考慮したスクリプトにして」と指示すれば自動で対応コードを生成します。

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

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

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

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

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

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ワークスペースにアクセスが必要な場合は、インテグレーショントークンを複数作成し、MCPの設定で別名のサーバーとして登録することで対応できます。

まとめ

Claude CodeとNotionの連携は、MCP経由（notion-mcp-server）を使うことで最もシームレスに実現できます。セットアップはNotionインテグレーションの作成・トークン取得→MCPサーバーの設定ファイル記述→Claude Codeの再起動という3ステップで完了します。Notion APIを直接叩くPythonスクリプトをClaude Codeに生成・実行させる方法も有効で、柔軟なデータ操作や既存プロジェクトへの組み込みに向いています。

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

関連記事

• Claude Codeとは（総合ガイド）
• claude code api 料金
• claude code codex 比較
• claude code cursor 比較
• claude code hooks