Claude Code × MCP × Notion連携で開発タスク管理を自動化する──エージェントワークフロー構築ハンズオン

結論：コードを書くだけでNotionのタスク管理が完結する世界

コードを書いたらNotionのタスクが自動で更新され、PRの要約がドキュメントに反映される──Claude CodeとMCPサーバーでこの仕組みを実際に構築してみました。

この記事を読むと、以下のことができるようになります。

• Notion連携MCPサーバーをセットアップし、Claude Codeからタスク操作を行う
• コード変更 → タスクステータス更新 → ドキュメント自動生成を一気通貫で実行するワークフローを構築する
• 同じMCPサーバーをCursor・Clineからも共有利用する

「AIエージェントにタスク管理まで任せたい」と感じている方に、そのまま使える構成をお渡しします。

---

完成形のワークフロー全体像

まず、最終的にどんな流れになるのかを先に見てください。

ポイントは、MCPサーバーが中央ハブとして機能し、どのAIエディタからでも同じNotion操作ができる点です。

---

環境・前提条件

項目	バージョン / 要件
Claude Code	最新版（CLIインストール済み）
Node.js	v18以上
Notionアカウント	ワークスペース管理者権限
Notion Integration	Internal Integration（APIキー発行済み）
OS	macOS / Linux（Windowsは WSL2 推奨）

Claude Codeのインストールがまだの方は、公式ドキュメントを参照してください。

npm install -g @anthropic-ai/claude-code

---

Step 1：Notion側の準備

1-1. Internal Integrationの作成

1. Notion Integrations にアクセス
2. 「New integration」をクリック
3. 名前を claude-code-mcp などに設定
4. Capabilitiesで Read content / Update content / Insert content をすべて有効化
5. 発行された Internal Integration Secret（ntn_ で始まる文字列）を控える

1-2. タスク管理データベースの作成

Notionにデータベースを作成し、以下のプロパティを設定します。

プロパティ名	型	選択肢（Selectの場合）
タスク名	Title	—
ステータス	Select	未着手 / 実装中 / レビュー中 / 完了
担当者	Person	—
PR URL	URL	—
概要	Rich Text	—

重要： データベースのページで「…」→「コネクションを追加」から、先ほど作成したIntegrationを接続してください。これを忘れるとAPIアクセスが403エラーになります。

---

Step 2：MCPサーバー（Notion連携）のセットアップ

2-1. 公式のNotion MCPサーバーを使う

Notion公式がMCPサーバーを提供しています。npxで直接実行できるため、グローバルインストールは不要です。

# 動作確認（この時点ではまだClaude Codeとは繋がない）
OPENAPI_MCP_HEADERS='{"Authorization":"Bearer ntn_xxxxx","Notion-Version":"2022-06-28"}' \
  npx -y @notionhq/notion-mcp-server

正常に起動すれば、stdio経由でMCPプロトコルを待ち受ける状態になります。

2-2. Claude Codeへの登録

Claude Codeでは claude mcp add コマンドでMCPサーバーを登録します。

claude mcp add notion-mcp \
  -e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer ntn_xxxxx","Notion-Version":"2022-06-28"}' \
  -- npx -y @notionhq/notion-mcp-server

登録されたか確認します。

claude mcp list

出力例：

notion-mcp: npx -y @notionhq/notion-mcp-server (stdio)
  Environment: OPENAPI_MCP_HEADERS={"Authorization":"Bearer ntn_xxxxx","Notion-Version":"2022-06-28"}

これで、Claude Codeのセッション内から notion-mcp のツールが使えるようになりました。

---

Step 3：CLAUDE.mdへのワークフロー記述

CLAUDE.md はClaude Codeの振る舞いを制御するプロジェクトレベルの設定ファイルです。ここにワークフローのルールを書くことで、Claude Codeが自律的にタスク管理を行います。

プロジェクトルートに CLAUDE.md を作成（または追記）します。

## Notion タスク管理ワークフロー

### データベース情報
- タスク管理DB ID: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
- ドキュメント格納先の親ページID: `yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy`

### ワークフロールール
1. タスクに着手する際、対象タスクのステータスを「実装中」に更新すること
2. 実装が完了したら、以下を実行すること：
   - タスクのステータスを「レビュー中」に更新
   - PR URLプロパティにPRのURLを記録
   - 概要プロパティに変更内容のサマリーを記録
3. 実装内容のドキュメントを、ドキュメント格納先の親ページ配下に子ページとして作成すること
   - ドキュメントには「変更概要」「影響範囲」「テスト方針」を含める

### MCPツールの使い方
- Notionのページ更新には `notion-mcp` の `PATCH /v1/pages/{page_id}` 相当のツールを使う
- ページ作成には `POST /v1/pages` 相当のツールを使う
- データベースの検索には `POST /v1/databases/{database_id}/query` 相当のツールを使う

ヒント： データベースIDは、NotionのデータベースページURLから取得できます。https://www.notion.so/xxxxx?v=yyyyy の xxxxx 部分（32文字のハイフンなし文字列）です。

---

Step 4：一気通貫フローの実行

実際にClaude Codeで動かしてみます。

4-1. タスクの確認と着手

claude

Claude Codeを起動し、以下のように指示します。

Notionのタスク管理DBから「未着手」のタスク一覧を取得して

Claude Codeは notion-mcp を通じてデータベースクエリを実行し、タスク一覧を返してくれます。

タスクを見つけました：
1. 「ユーザー認証のリファクタリング」（ID: abc123...）
2. 「APIレートリミットの実装」（ID: def456...）

どのタスクに着手しますか？

4-2. 実装からタスク更新まで

「ユーザー認証のリファクタリング」に着手して。
auth.tsのJWT検証ロジックをミドルウェアに切り出してほしい

この指示だけで、Claude Codeは以下を自動実行します。

黄色のステップがNotion更新、緑のステップがドキュメント生成です。CLAUDE.mdに記述したルールに従って、Claude Codeが自律的に判断・実行します。

4-3. 生成されるドキュメントの例

Notionに自動作成されるドキュメントは、以下のような構成になります。

## 変更概要
JWT検証ロジックをauth.tsからmiddleware/auth.tsに切り出し。
Express middlewareとして再利用可能な形に変更。

## 影響範囲
- src/middleware/auth.ts（新規）
- src/routes/api.ts（import変更）
- src/auth.ts（検証ロジック削除）

## テスト方針
- middleware/auth.tsの単体テストを追加済み
- 既存のE2Eテストで認証フローの回帰テスト確認済み

---

ハマりポイント3選と解決策

❌ 1. 「403 Forbidden」でNotion APIに接続できない

原因： データベースにIntegrationが接続されていない。

解決策： Notionのデータベースページ右上「…」→「コネクションを追加」で、作成したIntegration（claude-code-mcp）を選択してください。子ページにも権限が継承されますが、別階層のページには個別に接続が必要です。

❌ 2. MCPサーバーが起動するが、ツールが認識されない

原因： 環境変数 OPENAPI_MCP_HEADERS のJSON形式が壊れている。

解決策： シェルのクォーティングに注意してください。特にJSONの中にダブルクォートが含まれるため、シングルクォートで囲む必要があります。

# NG（ダブルクォート二重）
-e OPENAPI_MCP_HEADERS="{\"Authorization\":\"Bearer ntn_xxx\"}"

# OK（シングルクォートで囲む）
-e OPENAPI_MCP_HEADERS='{"Authorization":"Bearer ntn_xxx","Notion-Version":"2022-06-28"}'

また、Notion-Version ヘッダーの指定漏れも頻出原因です。必ず含めてください。

❌ 3. CLAUDE.mdの指示通りにClaude Codeが動かない

原因： 指示が曖昧、またはデータベースIDが間違っている。

解決策：

• データベースIDをNotionのURLから正確にコピーする（ハイフン付き/なし両方対応していますが、32文字であることを確認）
• CLAUDE.mdの指示は具体的な手順レベルで書く（「適宜更新して」ではなく「ステータスを"実装中"に変更して」のように）
• 最初のセッションで「CLAUDE.mdの内容を確認して」と指示し、認識されているか確かめる

---

Cursor・Clineからも同じMCPサーバーを共有利用する

MCPサーバーの設定はJSON形式の設定ファイルで管理されます。Claude Code、Cursor、Clineはそれぞれ異なる設定ファイルを参照しますが、MCPサーバーの定義内容は同一にできます。

Cursorの設定（.cursor/mcp.json）

プロジェクトルートに .cursor/mcp.json を作成します。

{
  "mcpServers": {
    "notion-mcp": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_xxxxx\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

Clineの設定（cline_mcp_settings.json）

VS CodeのCline拡張設定からMCPサーバーを追加します。形式はCursorとほぼ同じです。

{
  "mcpServers": {
    "notion-mcp": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "OPENAPI_MCP_HEADERS": "{\"Authorization\":\"Bearer ntn_xxxxx\",\"Notion-Version\":\"2022-06-28\"}"
      }
    }
  }
}

APIキーの管理について

上記の例ではAPIキーを直接記述していますが、チーム開発では以下の方法を推奨します。

• .env ファイル + .gitignore で管理し、設定ファイル内では環境変数を参照する
• Claude Codeの場合、claude mcp add の -e オプションはローカルの設定ファイルに保存されるため、リポジトリにはpushされない
• Cursor / Clineの場合、プロジェクトレベルの設定ファイルをコミットする際はAPIキーを除外し、READMEにセットアップ手順を記載する

---

まとめ

• MCPサーバーを中央ハブにすることで、Claude Code・Cursor・Clineのどこからでも同じNotionタスク管理ワークフローを実行できる
• CLAUDE.mdにワークフロールールを記述することで、コード変更→タスク更新→ドキュメント生成を自律的に一気通貫で実行させられる
• Notion Integration の権限設定とMCPの環境変数が最大のハマりポイント。セットアップ時に丁寧に確認すれば、あとはスムーズに動く

---

参考リンク

• Claude Code 公式ドキュメント
• Claude Code MCP設定ガイド
• CLAUDE.md の書き方
• Notion MCP Server（公式GitHub）
• Notion API 公式ドキュメント
• Model Context Protocol 仕様
• Cursor MCP設定ドキュメント