xserver-files-mcp

XServer のファイル操作を SFTP 経由で安全に行うローカル stdio MCP サーバー & CLI。

前提条件: Node.js 20+、SSH アクセスが有効な XServer アカウント。

セットアップガイド

以下の手順を上から順に進めてください。AI エージェント（Claude Code、Codex など）に依頼する場合も、この手順に沿って自動実行されます。[要ユーザー操作] のマークがあるステップのみ人間の操作が必要です。

Step 1: インストール

git clone https://github.com/mocchalera/xserver-files-mcp.git
cd xserver-files-mcp
npm install

動作確認（サーバー接続不要）:

XSERVER_FILES_CONFIG=config/example.config.json node src/cli.js servers

Step 2: XServer の情報を確認 [要ユーザー操作]

設定ファイルを作成するために、以下の情報が必要です。XServer サーバーパネル（https://secure.xserver.ne.jp/xapanel/login/xserver/server/）にログインして確認してください。

ヒント: XServer のドキュメントルートは通常 /home/<サーバーID>/<ドメイン>/public_html の形式です。

Step 3: 設定ファイルの作成

mkdir -p ~/.config/xserver-files-mcp
cp config/example.config.json ~/.config/xserver-files-mcp/config.json

~/.config/xserver-files-mcp/config.json を Step 2 で確認した情報に書き換えます:

{
  "defaultServer": "<サーバーID>",
  "localWorkspaceRoot": "~/Dev/xserver-sites",
  "servers": {
    "<サーバーID>": {
      "host": "<サーバーID>.xsrv.jp",
      "port": 10022,
      "username": "<サーバーID>",
      "privateKeyPath": "~/.ssh/xserver_<サーバーID>",
      "roots": {
        "<ドメイン>": "/home/<サーバーID>/<ドメイン>/public_html"
      }
    }
  }
}

localWorkspaceRoot はサイトファイルの pull 先です。このリポジトリの外であれば任意のパスで構いません。

Step 4: SSH 鍵の作成

ssh-keygen -t ed25519 -f ~/.ssh/xserver_<サーバーID> -C xserver-<サーバーID>

パスフレーズを設定した場合は、設定ファイルの passphraseEnv にパスフレーズを格納する環境変数名を指定し、その環境変数にパスフレーズを設定してください。

Step 5: SSH 公開鍵を XServer に登録 [要ユーザー操作]

この操作は XServer サーバーパネルで手動で行う必要があります。

1. 公開鍵の内容を確認:

   cat ~/.ssh/xserver_<サーバーID>.pub

2. XServer サーバーパネルにログイン

3. 「SSH設定」 を開く

4. SSH 設定が 「ON」 になっていることを確認（OFF なら ON に変更）

5. 「公開鍵登録・更新」 タブを開く

6. 上記の公開鍵の内容を全文貼り付けて 「確認画面へ進む」 → 「登録する」

Step 6: 接続テスト

ssh -p 10022 -i ~/.ssh/xserver_<サーバーID> <サーバーID>@<サーバーID>.xsrv.jp 'pwd'

Step 7: doctor で最終確認

node src/cli.js doctor

すべて [PASS] になればセットアップ完了です。

トラブルシューティング

Related MCP server: mcp-ssh

MCP 登録

Claude Code でこのリポジトリを開くと .mcp.json により自動登録されます。

他の MCP クライアント（Claude Desktop、VS Code など）では、設定に以下を追加:

{
  "mcpServers": {
    "xserver-files": {
      "command": "node",
      "args": ["/絶対パス/xserver-files-mcp/src/server.js"],
      "env": {
        "XSERVER_FILES_CONFIG": "/ホームディレクトリ/.config/xserver-files-mcp/config.json"
      }
    }
  }
}

パスは自分のマシンの絶対パスに置き換えてください。

CLI の使い方

node src/cli.js <command> [options]

診断

ファイル操作

ワークスペース操作

pull/push は wp-config.php、uploads、logs、backups、データベースダンプ、アーカイブをデフォルトで拒否します。--allow-sensitive はリスクを確認してから使用してください。

リダイレクト

node src/cli.js redirect old-site.example.com https://new-site.example.com --dry-run
node src/cli.js redirect old-site.example.com https://new-site.example.com

.htaccess にマーク付き 301 リダイレクトブロックを挿入・更新します:

# BEGIN xserver-files-mcp redirect old-site.example.com
<IfModule mod_rewrite.c>
RewriteEngine On
RewriteCond %{HTTP_HOST} ^(www\.)?old-site\.example\.com$ [NC]
RewriteRule ^(.*)$ https://new-site.example.com/$1 [R=301,L]
</IfModule>
# END xserver-files-mcp redirect old-site.example.com

共通オプション

すべての書き込みコマンドは --dry-run で変更をプレビューできます。--no-backup で自動バックアップをスキップ。--server <id> でデフォルト以外のサーバーを指定。

MCP ツール一覧

複数サーバー

設定ファイルの servers にエントリを追加。MCP では server_id、CLI では --server で指定:

node src/cli.js --server sv67890 roots

省略時は defaultServer が使われます。

安全性について

• すべてのパスは設定済みの roots[domain] 配下で解決されます。絶対パスと .. によるトラバーサルは拒否されます。

• 書き込み操作は既存ファイルをデフォルトで自動バックアップします。

• pull/push はリスクの高いパスをデフォルトで除外します: wp-config.php、uploads、logs、backups、SQL ダンプ、アーカイブ。

• replaceInFile と set_domain_redirect は読み取り・変換・書き込みを別々の SFTP 操作で行います。他のプロセスが同時に同じファイルを編集すると上書きされる可能性があります。

• 書き込み前に必ず --dry-run で変更をプレビューしてください。

• 秘密鍵はこのプロジェクトディレクトリの外に保管してください。

エージェント向け情報

• リポジトリ運用ルール: AGENTS.md

• SFTP ファイル操作スキル: .skills/xserver-files-operator/SKILL.md

• XServer パネル API スキル: .skills/xserver-mcp-operator/SKILL.md