notion-connections

Imported from xtone/ai_development_tools (common_development/skills/notion-connections/SKILL.md). Install upstream with npx skills add xtone/ai_development_tools --skill notion-connections. Copyright stays with the author.

Notion 接続の管理

Notion の MCP（https://mcp.notion.com/mcp）は、1つの登録が1つのワークスペースにしか接続できない。 ただし登録名を変えれば同じ URL を何個でも登録でき、認証も登録ごとに別々に持てる。 そこで「ワークスペースごとに名前付きの登録を1つ作る」ことで、切り替えずに複数のワークスペースを同時に使えるようにする。 ツール名は mcp__<登録名>__notion-fetch のように登録名で分かれるので、どのワークスペースを操作するかも呼び出し時点ではっきりする。

補助スクリプト: scripts/notion_mcp.py（設定を読むだけで書き換えない。認証情報は表示しない）

python3 "${CLAUDE_SKILL_DIR}/scripts/notion_mcp.py" list               # 今のプロジェクトから見える Notion 接続と、記録済みの接続先
python3 "${CLAUDE_SKILL_DIR}/scripts/notion_mcp.py" check-name <名前>   # 名前の形式と重複をチェック
python3 "${CLAUDE_SKILL_DIR}/scripts/notion_mcp.py" find-refs <名前>    # mcp__<名前> を参照している許可ルールなどを探す
python3 "${CLAUDE_SKILL_DIR}/scripts/notion_mcp.py" record <名前> <ワークスペース名> <ワークスペースID>   # 確認できた接続先を記録
python3 "${CLAUDE_SKILL_DIR}/scripts/notion_mcp.py" forget <名前>       # 記録を消す

シェル変数はコマンドの実行をまたいで残らないので、毎回このようにパスを書いて実行する。以下の list check-name などは、このスクリプトのサブコマンドを指す。

依頼が「追加」「一覧」「削除」「名前の付け替え」のどれかを判断して、該当する手順に進む。 どの手順でも、最初に list で現状を見せると、ユーザーが判断しやすい。

知っておくべき制約（ユーザーにも必要に応じて伝える）

• 認証は自動化できない。 OAuth の画面でワークスペースを選ぶのはブラウザでの手作業になる。 OAuth 画面は前回選んだワークスペースが初期選択になっていることが多く、そのまま許可すると別のワークスペースに繋がる。必ず右上で切り替えてもらう。
• 追加した登録は、今のセッションには現れない。 セッションは起動時の設定を使い続けるため。認証は新しいセッション（別ターミナルで claude）の /mcp で行ってもらい、接続先の確認は claude -p で行う（「追加」の手順 8）。
• 同じ名前がスコープ違いで複数あると、local が user より優先される。 意図せず古い登録が使われる原因になるので、追加・削除の前に list で確認する。
• 認証は「登録名＋URL」ごとに保存され、スコープをまたいで共有される。 local に認証済みの notion-x があれば、user に同名で追加した notion-x も最初から接続済みになる。 逆に、同名の登録のどれか1つを claude mcp remove すると、残った同名の登録の認証も消える（再認証が必要になる）。これは他プロジェクトの local 登録にも及ぶ。local から user へ移すときは、削除後に claude mcp list で状態を確かめ、必要なら認証し直してもらう。 同じ理由で、別のワークスペース用の登録に、他の登録と同じ名前を付けてはいけない（check-name が他プロジェクトの同名登録も NG にする）。
• claude.ai の Notion コネクタやプラグイン同梱の Notion MCP は、同じ URL の手動登録があると隠される。 手動登録を全部消すと、それらが再び表示される。
• ここでの「ワークスペース」は Notion のワークスペースのこと。登録名とワークスペースの対応は Notion 側からしか確かめられないので、notion-fetch(id: "self") で確認した結果を record で残しておく。 id: "self" は notion-fetch のスキーマには書かれていない使い方なので、エラーになったらワークスペース名を推測で記録せず、エラー内容をそのままユーザーに伝えて、ワークスペース名と ID を教えてもらう。

追加

1. list で既存の接続を見せる。
2. 接続したいワークスペースの名前（または用途）を聞く。
3. 登録名を提案する。基本形は notion-<ワークスペースの短い英字名>。
   • 例: 「Acme Corp」→ notion-acme、「Example Inc」→ notion-example、「個人」→ notion-personal
   • 日本語名なら、ローマ字か短い英単語にした案を出す。
   • 17 文字以内を勧める。ツール名 mcp__<名前>__<ツール名> が 64 文字を超えると、一部のツールが使えなくなる可能性があるため。
   • 提案を採るか、自分で名前を付けるかはユーザーに任せる。
4. check-name <名前> で形式と重複を確かめる。
   • NG なら理由を伝えて別の名前を決める。他プロジェクトの同名登録で NG になった場合は、認証が共有されてそちらのワークスペースに繋がってしまうためと説明する。
   • 注意:（長すぎる名前）が出たら、短い名前を勧める。それでもその名前を使うかはユーザーに任せる。
5. スコープを選んでもらう。
   • user（推奨）: すべてのプロジェクトで使える。ワークスペースは個人の所属で決まることが多いので、通常はこちら。 ただし、どのプロジェクトで作業していても Claude がそのワークスペースを読み書きできる状態になる。案件ごとに情報を分けたい（顧客の資料を他案件の作業中に触らせたくない）場合は local を勧める。
   • local: 今のプロジェクトだけで使う。そのプロジェクトでしか使わないワークスペースの場合。
6. 登録内容（名前・スコープ・URL）を示して、実行してよいか確認してから登録する。

   claude mcp add --transport http -s <user|local> <名前> https://mcp.notion.com/mcp

   local の場合は、対象プロジェクトのディレクトリで実行する。
7. 認証の手順を案内する（ユーザーの手作業）。
   1. 新しいセッションを起動する（別ターミナルで対象プロジェクトに移動して claude）
   2. /mcp で <名前> を選び、認証を始める
   3. ブラウザの OAuth 画面で、右上のワークスペースを目的のワークスペースに切り替えてから許可する
8. 接続先を確認する。認証が終わったと言われたら、claude -p で別の Claude を一度だけ起動して確かめる。 新しく起動するので、今のセッションに出てこない登録も使える。許可するツールは読み取りの notion-fetch だけにする。

   (cd ~ && claude -p 'mcp__<名前>__notion-fetch に id: "self" を渡して、ワークスペース名とワークスペース ID だけを答えて。エラーならエラー内容をそのまま書いて。他のツールは使わないで。' --allowedTools 'mcp__<名前>__notion-fetch')

   • cd ~ するのは、local の同名登録が優先されて別の登録を確かめてしまうのを避けるため（local で登録した場合は、cd ~ の代わりにそのプロジェクトのディレクトリへ移る）。
   • 括弧（サブシェル）で囲むのは、作業ディレクトリをホームに移したままにしないため。
   • claude -p が使えない環境なら、新しいセッションで同じ依頼をしてもらい、結果を受け取る。
   • エラーになったら、ワークスペース名を推測で記録しない（「知っておくべき制約」の最後の項目）。
   • 期待したワークスペースなら record <名前> <ワークスペース名> <ワークスペースID> で記録する。
   • 違っていたら、OAuth 画面で切り替え忘れた可能性が高い。/mcp → <名前> → 認証をクリア → 認証し直し（今度は切り替える）を案内し、もう一度確認する。

一覧

1. list を実行して結果を見せる。記録済みワークスペースは、過去に確認した時点の情報であることを添える。
2. 接続中かどうかを見たい場合は claude mcp list も実行する（すべての MCP に接続を試すので数秒かかる）。
3. 「今どこに繋がっているか」を確かめたい場合は、接続ごとに notion-fetch(id: "self") を実行し、記録と食い違っていれば record で更新する。 このセッションにツールが無い登録（セッション起動後に追加したもの）は、「追加」の手順 8 と同じく claude -p で確かめる。

削除

1. list で対象を確認し、どのスコープの登録を消すか特定する。
2. find-refs <名前> で、この名前を参照している設定を探して見せる。
   • find-refs は全プロジェクトを探すので、別のプロジェクトにある同名の local 登録に対する参照も混ざる。消す登録と同じものを指しているか（user スコープの登録か、同じプロジェクトの local 登録か）を見分けて、関係のない参照はそのままにする。
   • 許可ルール（settings*.json の mcp__<名前> や mcp__<名前>__…）は、削除後は使われずに残るだけ。消すか、新しい名前に書き換えるかをユーザーに聞く。
   • disabledMcpServers に名前が残っている場合も同じく聞く。
3. 同じ名前の登録がほかにないかを、手順 1 の list の結果（user / local と「他プロジェクトの local 登録」）で確かめる。
   • ある場合は、削除するとそれらの認証も消え、そちらでも認証し直しが必要になることを、該当するプロジェクト名を挙げて伝える。
4. 削除すると、その登録の認証も使えなくなる。同じ名前で登録し直すと認証からやり直しになることを伝えて、実行してよいか確認する。

   claude mcp remove <名前> -s <user|local|project>

5. 手順 3 で同名の登録があった場合は、claude mcp list で状態を確かめ、必要なら認証し直してもらう。
6. forget <名前> で記録も消す。同名の登録が残っていて同じワークスペースを指すなら、記録は残す。

名前の付け替え

登録名を直接変える方法はないので、「新しい名前で追加 → 確認 → 古い名前を削除」の順に行う。 先に削除すると、新しい登録の認証が終わるまで Notion が使えなくなるので、追加を先にする。 古い名前の削除は「削除」の手順どおりに行う。特に手順 3（同名の登録の認証も消える）を飛ばさない。 find-refs <古い名前> で見つかった許可ルールは、新しい名前（mcp__<新しい名前> / mcp__<新しい名前>__…）への書き換えを提案する。