claudeaibridge

claude.ai（無料プラン含む）に、あなた自身のマシン上での本格的なコーディングエージェント体験をもたらします。ファイル編集、シェルアクセス、git — すべてを、あなたが明示的に選んだプロジェクトフォルダ内で行い、操作は完全にウェブから完結します。IDEも、Claude Code のサブスクリプションも、ブラウザへの手動コピペも必要ありません。

仕組みはこうです。MCP（Claude Code と Claude Desktop がツール用に使うものと同じプロトコル）を喋る小さなローカルサーバーを起動し、それを公開 URL（ngrok または自分自身のドメイン/トンネル）経由で claude.ai の カスタムコネクタ として公開し、さらに、このマシン上であなただけが承認できる本物の OAuth 同意画面によってアクセスを制限します。

背景

claude.ai のコネクタは、リモートの MCP サーバーを通じて Claude が 他の サービス（Google Drive、GitHub など）のデータを読み書きできるようにするものです。このプロジェクトは、その同じ仕組みを自分のファイルシステムに向けたものです。Claude Code がローカルで行うことを、ブラウザのタブから操作できるようにしたものです。

Related MCP server: claude-agent-mcp

安全性の仕組み

これは、ウェブページからあなたのコンピュータ上のファイルを編集したり、シェルコマンドを実行したりする力を与えるものです。そのため設計は、「信頼」ではなく「封じ込め」に大きく頼っています。

• フォルダを選ぶのはあなたです。 コネクタがアクセスできるのは、このマシン上であなたが CLI を通じて明示的に登録したプロジェクトフォルダだけです。コネクタ自身が新しいフォルダを追加する手段はないので、コネクタ URL が漏れても「ディスク全体へのアクセス」にはなりません。

• ファイルシステムの封じ込め。 すべてのファイルツールは、ディスクに触れる前に、アクティブなプロジェクトルートに対してパスを解決・検証します。../ によるトラバーサルやシンボリックリンク経由の外部パスは拒否されます。シェルコマンドはサンドボックス（Linux では bwrap、macOS では sandbox-exec）内で実行され、それ以外のファイルシステムは読み取り専用になります。

• 本物の OAuth 同意。 接続は形だけの承認ではありません。claude.ai は このマシン上で ページを開く OAuth フローを完了し、登録済みプロジェクトが正確に一覧表示され、人間が Approve をクリックする必要があります。何も黙って許可されることはありません。

• 元に戻すための安全性。 ファイル編集は変更前にバックアップを保持し、削除はファイルを完全に削除せず、プロジェクト内にある .claudeaibridge/ フォルダのローカルごみ箱へ移動します。

• 監査証跡。 すべてのファイル/シェル操作は <project>/.claudeaibridge/audit.log に平文で追記されます。「Claude がここで実際に何をしたのか」はいつでも確認できます。

インタラクティブウィジェット

サポートしているホストでは、file_write と file_edit は、その変更内容を色分けされた行単位の diff としてチャット内に直接表示します。自動で行われ、追加の手順はありません。初期状態では開かれており、ファイル名をクリックすると折りたたみ／展開できます。どちらの場合も、Claude が受け取る結果データ（変更内容、バックアップ先、エラー詳細）はまったく同じです。ウィジェットはその結果データを表示しているだけであり、データが然り入替わるわけではありません。ウィジェット非対応のホストでも、ツールが返す通常の結果には影響しません。

サポートプラットフォーム

Linux と macOS に対応しています。Windows にはまだ対応していません（サンドボックス方式における Windows 相当の実装がないため）。

インストール

選択肢 1 — ビルド済みバイナリ。 PyInstaller で自分でビルドします（ソースからのビルド を参照）。現時点では別途ダウンロードだけで済む手順ではなく、ビルドする手順だけがあります。

選択肢 2 — ソースから、Python 3.10 以降:

git clone https://github.com/yemi-sh/claudeaibridge.git
cd claudeaibridge
python3 -m venv .venv
.venv/bin/pip install -e .

クイックスタート

claudeaibridge init

以下の手順で全体がまとめて説明されています。

1. ngrok の authtoken（無料でここから取得）を用意するか、自分自身のドメイン/トンネルを使うか、テストだけならローカルのみで行う。

2. 対話式ブラウザで、claude.ai から操作できるプロジェクトフォルダを選択する（矢印キーで移動、Space で選択、入力で検索）。

3. バックグラウンドサービス（Linux では systemd、macOS では launchd）としてインストールし、コネクタ URL を表示する。ターミナルを閉じても実行は継続します。

その後、claude.ai で 設定 → コネクタ → カスタムコネクタを追加 を選び、表示された URL を貼り付けます。claude.ai が承認用のブラウザタブを開くので、同意ページで「承認」をクリックすれば接続完了です。Claude に利用可能なプロジェクト一覧を尋ね、プロジェクトを選択して作業を始められます。

いつでも claudeaibridge status で確認できます。サービス管理者がない環境（Windows、または systemd ユーザーセッションがない Linux 環境）では、init はフォアグラウンドで実行されます。

コマンドリファレンス

claudeaibridge init

上記で説明した対話式セットアップウィザードです。再実行しても安全です。各ステップで現在の設定が表示され、維持するか変更できます。再実行すると、そのとき選んだ内容でバックグラウンドサービスが再インストールされ、以前のものと完全に置き換わります。

claudeaibridge status

バックグラウンドサービスの稼働状況と、最後に出力されたコネクタ URL を表示します。

claudeaibridge stop

バックグラウンドサービスを停止してアンインストールします（systemd/launchd ユニットを停止するだけでなく、完全に削除します）。init または serve を再実行するまでコネクタはオフラインになります。

Projects

claudeaibridge add-project ~/code/my-repo   # register a specific folder
claudeaibridge add-project                  # or pick one (or several) interactively
claudeaibridge edit-project ~/code/my-repo  # unregister that folder directly
claudeaibridge edit-project                 # or open the picker, pre-checked with
                                             # everything registered — check/uncheck
                                             # to add or remove
claudeaibridge list-projects                # print all registered paths

プロジェクトの識別名は、その解決済みファイルシステムパスだけです。別途覚える名前はありません。

claudeaibridge serve

指定したフラグを使って MCP サーバーをバックグラウンドサービスとしてインストール／起動し、コマンドは終了します（init はウィザードの最後に同じ処理を呼び出します）。ターミナルを操作している時間はありません。バックグラウンドサービスがすでに稼働している場合、serve は再インストールせず、コネクタ URL を表示するだけです。

例:

claudeaibridge serve --ngrok                                    # install+start as a service
claudeaibridge serve --base-url https://your-domain.example     # bring your own tunnel
claudeaibridge serve --no-auth --foreground                     # local-only testing, blocking
claudeaibridge serve --transport stdio                          # local MCP client

claudeaibrbridge ngrok

claudeaibridge ngrok set-authtoken <token>   # one-time setup
claudeaibridge ngrok status                  # check whether a token is configured

ngrok の各アカウント（無料プラン含む）には、静的ドメインが1つ永久に割り当てられています。エージェントは認証トークンだけで自動的にそれにバインドします。他に設定するものはありません。有料プランでカスタムドメインを使う場合は、ngrok http --domain=... プロセスを自分で実行し、claudeaibridge serve に --base-url を指定してそのドメインを指すようにします（--ngrok は利用しません）。

設定

設定はすべて ~/.config/claudeaibridge/（または $XDG_CONFIG_HOME/claudeaibridge）に置かれます。

• projects.json — 登録済みプロジェクトの許可リスト

• ngrok_authtoken — ngrok トークン（chmod 600）

• oauth_state.json — OAuth クライアントとトークンを永続化することで、claude.ai でのコネクタ確認が毎回の再起動後にもう一度ではない、初回だけの作業になる

• connector_url — サーバーが最後に出力したコネクタ URL。サーバーがバックグラウンドサービスとして動作していても（つまり stdout が観られなくても）、claudeaibridge status が表示すべき内容を持っている

ソースからのビルド

pip install -e '.[build]'
./packaging/build.sh

生成物は dist/claudeaibbridge-<os>-<arch> です。PyInstaller はクロスコンパイルできないため、実行しているプラットフォーム用のものだけを生成します。

テストの実行

pip install -e '.[test]'
python tests/smoke_test.py        # core MCP tools, in-memory
python tests/oauth_flow_test.py   # full OAuth flow against a real subprocess
python tests/tunnel_test.py       # live ngrok test — needs NGROK_AUTHTOKEN set

既知の制限

• Windows が未対応で、init のバックグラウンドサービス手順にはシステムが（Linux）または launchd（macOS）が必要です。どちらもない場合はフォアグラウンド実行に戻ります。

• バックグラウンドサービスの launchd（macOS）コードパスは実装されていますが未検証です。開発時に利用できた Linux（systemd）のみでのビルド・テストためです。

• ウィジェットは現在、file_write と file_edit が自身の変更を色付き diff として表示する機能だけです。実稼働中の claude.ai に対する動作を確認済みです。

ライセンス

GPL-3.0-or-later。