Notion MCPで仕様書を読みながらコードを書く

Notion MCPでできること

Notion MCPをClaude Codeに接続すると、Notionのページ・データベースをClaude Codeが直接読み込めます。

仕様書を読みながら実装
タスクリストを参照して作業を進める
設計ドキュメントを確認しながらコードを書く
実装完了後にNotionのステータスを自動更新

「Notionの仕様書を読んで実装して」と依頼するだけで、Claudeが仕様書を直接参照しながら実装してくれます。毎回仕様書をコピペする手間がなくなります。

※MCP: Model Context Protocol の略。Claude Codeと外部ツール（GitHub・Supabaseなど）を接続するための標準プロトコル。

セットアップ手順

1. Notion Integration を作成する

Notion Developers にアクセス
「New integration」をクリック
名前（例: Claude Code）、接続するワークスペースを設定
「Capabilities」で必要な権限を選択:
- Read content — 必須（仕様書を読む）
- Update content — タスクのステータス更新に必要
「Submit」でIntegrationを作成
「Internal Integration Token」をコピー

2. Notionページに Integration を接続する

Claude Codeに読ませたいページ・データベースで：

右上の「…」メニュー → 「Connections」
作成したIntegration（Claude Code）を追加

3. settings.json に設定を追加する

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/client-mcp"],
      "env": {
        "NOTION_API_KEY": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

環境変数を使う場合：

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@notionhq/client-mcp"],
      "env": {
        "NOTION_API_KEY": "${NOTION_API_KEY}"
      }
    }
  }
}

# .bashrc または .zshrc に追加
export NOTION_API_KEY="secret_xxxxxx"

※環境変数: APIキーやデータベース接続情報など、コードに直接書きたくない値をOSやサーバーに設定する仕組み。※API: Application Programming Interface の略。外部サービスとプログラム間でデータをやりとりするための接続口。

実際の使用例

仕様書を読んで実装する

「Notionの以下のページに仕様書があります。読んで実装してください。
https://www.notion.so/myworkspace/xxxxxx

実装言語: TypeScript (Next.js)
まず仕様書を読んで、実装前に要点を整理してください。」

タスクリストに従って作業する

「NotionのスプリントバックログのページID: xxxxxxxx
このバックログのうち、「実装待ち」のタスクを確認して、
一番優先度の高いものから実装を始めてください。
実装が完了したらステータスを「完了」に更新してください。」

設計ドキュメントとコードを照合する

「Notionの設計ドキュメント（https://notion.so/xxx）と
現在のコードベースを比較して、
設計と実装が乖離している箇所を教えてください。」

※TypeScript: JavaScriptに型定義を追加した言語。型チェックによりバグを事前に発見しやすくなる。

Notionページの書き方のコツ

Claude CodeがNotionを読みやすくなる書き方のコツです。

見出しと構造を明確にする

## 機能概要
[何をする機能か]

## 入力
- パラメータ1: [型] [説明]
- パラメータ2: [型] [説明]

## 出力
- 成功時: [返り値の説明]
- エラー時: [エラーの種類と処理]

## 制約・バリデーション
- [制約1]
- [制約2]

コードブロックを使う

NotionのコードブロックはClaude Codeが正確に読み取れます。SQL例、APIのリクエスト/レスポンス例、型定義などはコードブロックで書きましょう。

データベースのプロパティを活用する

タスクデータベースに「実装担当」「ステータス」「優先度」プロパティを設定しておくと、Claudeが「未着手・高優先度のタスク一覧」などのフィルタリングができます。

注意点・制限事項

画像・ファイルは読み取れない

NotionページにアップロードされたPDFや画像は、現在の Notion MCPでは読み取れません。テキストベースの仕様書として書くことを推奨します。

ページの巨大化に注意

Claudeがページ全体を読み込むため、一つのページが巨大だとコンテキストを大量に消費します。ページを適切に分割することをお勧めします。

更新の遅延

Notionのデータは更新後すぐに反映されますが、キャッシュにより数秒の遅延が発生する場合があります。

※コンテキスト: Claudeが一度に記憶・参照できる会話・コードの範囲。上限を超えると古い情報が失われる。※キャッシュ: 一度取得したデータを一時的に保存しておき、同じリクエストへの応答を速くする仕組み。