Skip to main content
Glama
xserver-files-mcp

xserver-files-mcp

by mocchalera

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/)にログインして確認してください。

必要な情報

確認場所

例

サーバー ID

サーバーパネル上部に表示

sv12345

ホスト名

サーバー情報 → ホスト名

sv12345.xsrv.jp

操作対象のドメイン

ドメイン設定 → ドメイン一覧

example.com

ドキュメントルート

ドメイン設定 → ドメイン一覧の「ドキュメントルート」列

/home/sv12345/example.com/public_html

ヒント: 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] になればセットアップ完了です。

トラブルシューティング

doctor の出力

原因

対処

[FAIL] Config loaded

設定ファイルが見つからないか JSON が不正

~/.config/xserver-files-mcp/config.json の存在と JSON 構文を確認

[FAIL] SSH key exists

秘密鍵ファイルが見つからない

Step 4 の鍵作成を確認。パスが設定ファイルの privateKeyPath と一致しているか確認

[FAIL] SFTP connection

SSH 接続に失敗

Step 5 の公開鍵登録を確認。ssh -p 10022 ... で手動テスト

Related MCP server: mcp_shell_tools

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]

診断

コマンド

説明

doctor

設定ファイル、SSH 鍵、SFTP 接続をチェック

servers

設定済みサーバー一覧を表示(接続不要)

roots

設定済みドメインルート一覧を表示

--version

バージョンを表示

ファイル操作

コマンド

説明

ls <domain> [path]

リモートファイル一覧

read <domain> <path>

リモートの UTF-8 テキストファイルを読み取り

write <domain> <path> --from <file>

リモートにファイルを書き込み(既存ファイルは自動バックアップ)

replace <domain> <path> --find <text> --replace <text>

テキストの完全一致置換(自動バックアップ)

backup <domain> <path>

タイムスタンプ付きリモートバックアップを作成

backups <domain> <path>

ファイルのリモートバックアップ一覧

cleanup-backups <domain> <path> [--keep N]

古いバックアップを削除し、最新 N 件を保持(デフォルト 5)

ワークスペース操作

コマンド

説明

workspace <domain>

ドメイン用のローカルワークスペースを作成

pull <domain> <path>

リモートファイルをローカルワークスペースに取得

push <domain> <path>

ローカルワークスペースのファイルをサーバーに送信(自動バックアップ)

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 ツール一覧

ツール

説明

list_servers

設定済みサーバー一覧

list_roots

プロファイルのドメインルート一覧

init_site_workspace

ドメイン用のローカルワークスペースを作成

list_files

リモートファイル一覧

read_file

UTF-8 テキストファイルを読み取り

pull_file_to_workspace

リモートファイルをローカルワークスペースに取得

push_file_from_workspace

ローカルワークスペースのファイルをリモートに送信

backup_file

リモートファイルのタイムスタンプ付きバックアップを作成

write_file

UTF-8 ファイルを書き込み(既存ファイルは自動バックアップ)

replace_in_file

テキストの完全一致置換(自動バックアップ)

set_domain_redirect

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

複数サーバー

設定ファイルの 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 で変更をプレビューしてください。

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

エージェント向け情報

このリポジトリは公開配布向けに、エージェント手順の正本を skills/ に置いています。

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

  • 初期セットアップスキル: skills/xserver-files-setup/SKILL.md

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

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

互換性のため、同じスキルを以下の project-local view からも参照できます:

  • .claude/skills/

  • .agents/skills/

  • .gemini/skills/

  • .cursor/skills/

  • .grok/skills/

  • .antigravity/skills/

Cursor 向けには .cursor/rules/xserver-files.mdc も同梱しています。CLAUDE.md、GEMINI.md、GROK.md、ANTIGRAVITY.md は AGENTS.md と skills/ への薄い入口です。

GitHub から clone した場合は上記 view が symlink として含まれます。npm tarball では symlink view は含めず、skills/ の正本と .agent-support/ の再生成スクリプトを配布します。

agent view を再生成・検証するには:

npm run agent:install
npm run validate:agent-support

symlink が使えない環境では copy view を生成できます:

npm run agent:install -- --copy --force

Available Tools

13 tools
add_rootAdd domain root to configA

Register a new domain root for a server profile. Infers the remote path from the server username if not specified, verifies the directory exists via SFTP, and saves to the config file.

Inputs: domain (required), root, dry_run, server_id.

backup_fileBackup remote fileA

Create a timestamped dotfile backup next to a remote file.

Inputs: path (required), domain (required), label, server_id.

discover_rootsDiscover domain roots on serverA
Read-only

Scan the server home directory for domains with public_html and show which ones are not yet configured. Use add_root to register any you want to manage.

Inputs: server_id.

init_site_workspaceInitialize local site workspaceA

Create the local workspace directory for a configured domain outside this repository and add a protective .gitignore.

Inputs: domain (required), dry_run, server_id, workspace_root.

list_filesList remote filesA
Read-only

List files under a configured domain root over SFTP.

Inputs: domain (required), path, server_id.

list_rootsList domain rootsA
Read-only

List configured domain roots for a server profile.

Inputs: server_id.

list_serversList configured XServer profilesA
Read-only

List configured XServer connection profiles and domain roots without connecting to SFTP.

Inputs: no named parameters.

pull_file_to_workspacePull remote file to local workspaceA

Read one remote UTF-8 file and write it under the matching local site workspace path. Existing local files are backed up by default.

Inputs: path (required), domain (required), dry_run, server_id, +3 more.

push_file_from_workspacePush local workspace fileA
Destructive

Read one local workspace file and write it to the matching remote path. Existing remote files are backed up by default.

Inputs: path (required), domain (required), backup, dry_run, +4 more.

read_fileRead remote fileB
Read-only

Read a UTF-8 text file under a configured domain root over SFTP.

Inputs: path (required), domain (required), server_id.

replace_in_fileReplace text in remote fileA
Destructive

Read a file, replace all exact text matches, and write it back with backup by default.

Inputs: find (required), path (required), domain (required), backup, +4 more.

set_domain_redirectSet domain redirectA
Destructive

Insert or update a marked .htaccess 301 redirect block for a configured source domain. Creates a backup by default.

Inputs: domain (required), to_url (required), path, backup, +4 more.

write_fileWrite remote fileA
Destructive

Write a UTF-8 text file under a configured domain root. Existing files are backed up by default.

Inputs: path (required), domain (required), content (required), backup, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 13 tools

    Disambiguation4/5

    Most tools have clear distinct purposes (listing, reading, writing, backing up, configuring). However, pull_file_to_workspace overlaps with read_file (both read remote content) and push_file_from_workspace overlaps with write_file (both write remote), which could cause misselection without careful descriptions.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern (e.g., list_files, read_file, write_file, set_domain_redirect). Even the longer names like pull_file_to_workspace and push_file_from_workspace maintain the pattern with clear prepositions, so the naming convention is uniform.

    Tool Count5/5

    13 tools is well-scoped for a file management server covering configuration, file operations, backups, and workspace sync. Each tool addresses a specific need without unnecessary bloat, making the count appropriate for the domain.

    Completeness2/5

    The tool surface covers core file operations (create, read, update) and backups, but notably lacks a delete tool and directory management (mkdir/move/copy). This is a significant gap for a file management server, as agents cannot complete full file lifecycle workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      A lightweight MCP server for basic file operations, enabling reading, writing, and listing files securely via the Model Context Protocol.
      3
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      SSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.
      ISC
    • A
      license
      B
      quality
      C
      maintenance
      A secure file management MCP server enabling file operations like listing, reading, creating, renaming, moving, copying, deleting, and searching within a restricted workspace.
      10
      MIT