Command-Line MCP Server

リモートのModel Context Protocolサーバーで、単一のツールrun_commandを公開し、Claude（Claude DesktopのConnectors機能経由）がこのサーバーを実行しているマシン上でシェルコマンドを実行できるようにします。

このサーバーはOAuth 2.1（Dynamic Client Registration + PKCE）を実装しています。Claude DesktopコネクタはOAuthハンドシェイクを必須とするためです。認証サーバーのないコネクタはサインイン時に拒否されます。このサーバーは認可を自動承認します（ユーザープロンプトなし）。個人用のトンネル公開サーバーであれば問題ありません。

⚠️ セキュリティ警告: このサーバーに到達でき、（自動の）OAuthフローを完了できる人は誰でも、そのサーバーを実行しているユーザーとして任意のコマンドを実行できます。プライベートトンネル（cloudflared / ngrok）経由でのみ公開し、決してパブリックネットワーク上には公開しないでください。

仕組み

• トランスポート: Streamable HTTP（Claude Desktopコネクタが要求するトランスポート）。

• ステートレス: 各リクエストで新しいサーバー/トランスポートインスタンスを起動します（セッションストアは不要）。

• エンドポイント: POST /mcp

• ヘルスチェック: GET /health

ツール

run_command

シェルコマンドを実行します。Windowsでは、shell: "powershell"を渡さない限り、デフォルトのシェルはcmd.exeです（ls/pwdではなくdir、cdを使用）。

get_info

OS、アーキテクチャ、デフォルトシェル（Windowsではcmd.exe）、現在の作業ディレクトリを返します。クライアントがどのシェルを使うべきか判断できるよう、一度呼び出してください。

read_file

テキストファイルを読み取ります（オプションのoffset/limit行範囲）。pathは絶対パスまたはcwdからの相対パスです。

list_files

ディレクトリを一覧表示します。recursive: trueでツリーを走査します（深さは4に制限）。

edit_file

正確な文字列置換 — コードを編集する推奨方法です（シェルエスケープ不要）。 path、old_text、new_text、オプションのreplace_all。old_textはreplace_allが設定されていない限り一意である必要があります。短いdiffを返します。

apply_patch

git apply（--3wayフォールバック付き）でユニファイドdiffを適用します。cwd = リポジトリルート、patch = diffテキスト。

write_file

ファイルに完全なコンテンツを書き込みます（overwrite、またはappend）。

batch_read

1回の呼び出しで複数のファイルを読み取ります。files: { path, offset?, limit? }の配列。

batch_edit

1回の呼び出しで1つ以上のファイルに多数の正確なテキスト編集を適用します。トランザクション式: すべてのold_textがファイル書き込み前に検証されるため、一致しない/曖昧な一致はバッチ全体を中止します（何も変更されません）。各編集: { path, old_text, new_text, replace_all? }。

ネイティブgitパススルー

git_status（-sb）、git_diff（staged + pathsオプション）、git_log（max_count、revision）、git_show（revision）。それぞれオプションのcwdを受け取ります。

すべてのファイルパスはサーバーを実行しているホスト上で解決されます — それらはClaudeのサンドボックスではなく、このマシンを指しています。

ローカルで実行

npm install
npm start
# server listens on http://localhost:3000/mcp

オプションの環境変数: PORT、CMD_TIMEOUT_MS、CMD_MAX_BUFFER。

npm startはstart.jsを実行し、サーバー起動前にポート3000を解放します（保持しているプロセスを強制終了）。そのためEADDRINUSEに遭遇することはありません。

Claude Desktopに公開する

オプションA — Cloudflare Worker（安定したURL、trycloudflare不要、ドメイン不要）

小さなローカルエージェントがCloudflare WorkerへのWebSocketを開いたままにし、それが安定したパブリック*.workers.dev MCPエンドポイントになります。Workerは、エージェント（PROXY_SECRETで認証）が接続されている間だけ、あなたのマシンに中継します。

1. wrangler login（無料のCloudflareアカウント）。

2. デプロイ: wrangler deploy → URLをメモします。例: https://command-line-mcp.<subdomain>.workers.dev。

3. シークレットを設定します（gitignoreされた.dev.varsにすでにある同じ値）: wrangler secret put PROXY_SECRET（.dev.varsからPROXY_SECRETを貼り付け）。

4. エージェントをデプロイしたWorkerに向けます: .dev.varsのWORKER_URLをそのURLに設定。

5. マシン上で両方を実行:

   npm start          # the MCP server on :3000
   npm run agent      # connects to the Worker with the secret

6. Claude Desktopで: Customize → Connectors → Add custom connector、https://command-line-mcp.<subdomain>.workers.dev/mcpを貼り付け。

デプロイせずにローカルテスト: wrangler dev --port 8787（Workerを:8787で実行）、その後npm run agent — エージェントは.dev.varsからWORKER_URLを読み取ります。

オプションB — cloudflared / ngrokトンネル（一時的なURL）

Claude DesktopコネクタはHTTPS URLを必要とするため、サーバーをローカルで実行してトンネルします:

cloudflared tunnel --url http://localhost:3000 --protocol http2
# or: ngrok http 3000

生成されたhttps://… URLをコピーして/mcpを追加します。例: https://abc-123.trycloudflare.com/mcp。

Claude Desktopに追加

1. Customize → Connectors → Add custom connectorを開きます。

2. URL（/mcp付き）を貼り付けます。例: オプションAのWorker URL。

3. Command-Lineという名前を付けます。

4. 保存します。ClaudeがOAuthメタデータを検出し、クライアントを登録し、ブラウザで（自動承認の）認可エンドポイントを開き、リダイレクトして準備完了になります。「OAuth Client ID」を手動で入力する必要はありません — DCRが処理します。

Claudeなしでテスト

MCP Inspectorを使用:

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP, URL: http://localhost:3000/mcp

堅牢化（個人以外の用途向け）

OAuthはすでに実装されています（oauthProvider.jsを参照）。個人用トンネルを超える用途では、以下を行う必要があります:

1. 自動承認のauthorize()を実際の同意画面に置き換えるか、少なくとも許可リスト方式のリダイレクトURI / クライアントセットを使用する。

2. クライアント/トークンを永続化する（現在はインメモリ — 再起動でリセットされます）。

3. 安定したHTTPSドメインの背後でホストする（例: VPS、Cloudflare Workers、Fly.io）。

4. 許可されたコマンドの許可リストを検討して、爆発半径を制限する。

ライセンス

MIT