O2n

🤔 なぜ o2n？

Notion の標準インポートは Obsidian 特有の書き方を解釈しないため、大きな vault ほど手直しが現実的でなくなります。o2n は vault 全体を解析してから Notion のデータ構造に変換します。

🚀 3 分で始める

必要なもの: Node.js 22.13 以上・Notion のトークン・Obsidian の vault（プラグイン・MCP サーバーから使う場合は .obsidian フォルダのある vault に限ります）

以下の手順は npx で実行します。npm i -g @tk_wfl/o2n-cli でインストールすると、npx @tk_wfl/o2n-cli の代わりに o2n と打つだけで使えます（このページの o2n … はこの意味です）。

1. Notion のトークンを用意する

Notion 開発者ポータル → Personal access tokens で New token → 名前・有効期限を選んで作成し、表示されたトークンを控えます（作成時にしか表示されません）。

export NOTION_TOKEN=ntn_xxx
# または一度だけ保存（プロンプトに貼り付け。以降は設定不要）
npx @tk_wfl/o2n-cli login --token

💡 個人アクセストークン（PAT） なら、移行先ページを integration に接続する手順が不要で、Free プランのブロック上限（後述）の対象外です。他の方法は Notion との連携方法 を参照。

2. 計画を作る

npx @tk_wfl/o2n-cli plan <vaultのパス> --parent <移行先 Notion ページの ID>

移行先ページの ID は、Notion でそのページの「リンクをコピー」をしたときの URL の末尾にある 32 桁の英数字です。

フォルダごとに「ページ階層」か「データベース」かを対話で選べます（frontmatter が揃っているフォルダは自動でデータベース化を提案）。

3. 試してから、移行する

npx @tk_wfl/o2n-cli migrate <vaultのパス> --dry-run   # 書き込まずにシミュレーション
npx @tk_wfl/o2n-cli migrate <vaultのパス>             # 本番
npx @tk_wfl/o2n-cli verify  <vaultのパス> --deep      # Notion の実ページと照合

途中で止まっても npx @tk_wfl/o2n-cli resume <vaultのパス> で続きから再開できます。

🧑‍💻 コマンドが苦手な方へ: Claude のプラグイン（Claude Code / Cowork）か MCP サーバーとして使うと、「この vault を Notion に移行して」と話しかけるだけで進められます → MCP サーバーとして使う

📖 コマンド一覧

• 移行後にノートを別フォルダへ移動・改名しても、resume で検知して Notion 上の同じページを移動・改名します（内容も同時に変えた場合は新しいページとして作成）
• migrate --dry-run のレポートは .o2n/report.dry-run.md に書かれ、本番の report.md を上書きしません
• --embed-mode inline: ![[ノート]] の埋め込みを、リンクではなく本文にその場で展開します（![[ノート#見出し]] はそのセクションのみ）
• 終了コード: 0 全件成功 / 1 一部失敗・不一致あり / 2 致命的エラー

🔑 Notion との連携方法

トークンの渡し方は2通りです。どちらもコマンドライン引数では受け取りません（シェル履歴への漏洩防止）。

• 環境変数 NOTION_TOKEN に設定する
• o2n login --token で保存する：プロンプトに貼り付ける（入力は表示されません）か、標準入力で渡します。Notion に接続して有効なことを確かめてから ~/.o2n/credentials.json（パーミッション 600）に保存し、以降は CLI と MCP サーバーが自動で使います。解除は o2n logout

npx @tk_wfl/o2n-cli login --token

両方ある場合は NOTION_TOKEN が優先されます（空文字なら未設定扱い）。

npx @tk_wfl/o2n-cli login

🤖 MCP サーバーとして使う

Claude のプラグインとして使う（Claude Code / Cowork）

plugin/ は Claude のプラグインです。MCP サーバーの起動設定が入っており、トークンなどは有効化したときに表示される設定画面で入力します。このリポジトリはプラグインのマーケットプレイスにもなっているので、GitHub のリポジトリ名 TK-WFL/o2n を指定して追加できます。

Claude Code では次を実行します。

/plugin marketplace add TK-WFL/o2n
/plugin install o2n@o2n

手元で変更を試すときは、clone したフォルダを直接読み込めます。

git clone https://github.com/TK-WFL/o2n.git
claude --plugin-dir ./o2n/plugin

Cowork では、プラグインの追加画面でマーケットプレイスとして TK-WFL/o2n を追加し、表示される o2n をインストールします。そのあと、下の「Cowork で使う場合」の設定を保存します。

プラグインが動くのは、ローカルの MCP サーバーを起動できる Claude Code と Cowork です。claude.ai のチャットはローカルの MCP サーバーを起動しません。

Cowork で使う場合は設定画面が出ないので、先にターミナルで次を実行して設定を保存します。プラグインの設定が空のときは、MCP サーバーがこの保存内容を使います。

npx @tk_wfl/o2n-cli login --token          # Notion のトークン
npx @tk_wfl/o2n-cli mcp allow <vaultのパス>  # 読んでよい vault
npx @tk_wfl/o2n-cli mcp write on            # 本実行したいとき。確認フレーズを設定

mcp allow と mcp write on はターミナルで直接実行したときだけ受け付けます（Claude がツール経由で自分に権限を与えられないようにするため）。保存先は ~/.o2n/mcp-settings.json（パーミッション 600）です。何を読み・書き・送るかは plugin/README.md にまとめています。

MCP 設定に直接登録する

Claude Desktop / Claude Code の MCP 設定に npx -y @tk_wfl/o2n-mcp-server を登録します。

{
  "mcpServers": {
    "o2n": {
      "command": "npx",
      "args": ["-y", "@tk_wfl/o2n-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_xxx",
        "O2N_ALLOWED_VAULTS": "/absolute/path/to/vault"
      }
    }
  }
}

🔒 安全設計: 許可した vault（O2N_ALLOWED_VAULTS または o2n mcp allow）以外へはアクセスできません。Notion への本実行は既定で無効です。書き込み許可（O2N_ENABLE_MCP_WRITE=1、true も可。または o2n mcp write on）と確認フレーズ（O2N_MCP_WRITE_TOKEN または o2n mcp write on で設定）を用意し、commit_migration にそのフレーズを渡す必要があります。環境変数に値があれば環境変数が優先されます。失敗・拒否の応答は isError 付きで返ります。

🔄 変換される内容

フォルダ直下のノートの 60% 以上が共通の frontmatter キーを 3 つ以上持つ場合、そのフォルダの データベース化を自動提案します（最終判断は plan で行います）。

⏱ 所要時間と制限

• 目安: 1,000 ノート＋500 添付 ≒ API 呼び出し 4,000〜5,000 回 ≒ 約 30〜40 分（既定 2 req/秒）
• Business プラン以上なら O2N_REQUESTS_PER_SECOND=8（1〜10）で短縮できます。ノートは同じ数だけ並行に処理されます（ページの並び順は保たれます）。429 は Retry-After に従って自動で待ちます
• Notion Free プランのブロック上限（2026 年 9 月〜）: 複数メンバーの Free ワークスペースは生涯 1,000 ブロックが API にも適用されます（公式リファレンス）。scan / plan が推定ブロック数で事前警告し、上限に達した場合は即座に中断して resume で再開できます。PAT・有料プラン・メンバー 1 人の Free は対象外です

🛡 セキュリティ

• トークンは環境変数 NOTION_TOKEN か ~/.o2n/credentials.json（パーミッション 600、o2n login --token で作成）にのみ保存。MCP の許可 vault・確認フレーズの保存先 ~/.o2n/mcp-settings.json も同じ保護
• vault 本体は 常に読み取り専用。書き込むのは .o2n/ ディレクトリのみ
• frontmatter は YAML のみ受け付け、---js / ---json などはそのノートだけを安全にスキップ
• vault 内のシンボリックリンクは辿らない。.o2n/ と ~/.o2n/ は symlink / hardlink / TOCTOU 攻撃を防ぐ形で読み書き
• .o2n/state.json は vault・計画・Notion ワークスペースに署名で結合され、取り違えを検知
• 悪意のある vault で処理をハングさせる ReDoS への対策済み
• Notion API 以外への通信なし（テレメトリなし）。npm パッケージは Trusted Publishing（OIDC）で provenance 付きで公開
• 何を読み・送り・保存するか、その消し方は プライバシーポリシー にまとめています
• 脆弱性を見つけた場合は、公開の Issue ではなく SECURITY.md の手順（非公開の Security Advisory）で報告してください

🧑‍🔧 開発

npm install
npm run build
npm test

packages/
  core/          # scanner / planner / converter / migrator / state / notion / report
  cli/           # o2n コマンド（core の薄いラッパー）
  mcp-server/    # stdio MCP サーバー（core の薄いラッパー）
plugin/        # Claude のプラグイン（MCP サーバーの起動設定と設定項目）
services/
  auth-proxy/    # `o2n login` 用の OAuth コード交換代理（Cloudflare Worker）
fixtures/test-vault/  # 全構文網羅のテスト用 vault
scripts/verify-release.mjs  # npm 公開前の内容・チェックサム検証
docs/
  e2e.md         # 手動 E2E 手順書
  questions.md   # 実装判断と実ワークスペースでの検証記録
  spec.md        # セキュリティ境界・永続化データの仕様

不具合報告・要望は Issues へ。変換がうまくいかない記法があれば、その断片を添えてもらえると助かります。