xserver-files-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@xserver-files-mcp list files on example.com"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 serversStep 2: XServer の情報を確認 [要ユーザー操作]
設定ファイルを作成するために、以下の情報が必要です。XServer サーバーパネル(https://secure.xserver.ne.jp/xapanel/login/xserver/server/)にログインして確認してください。
必要な情報 | 確認場所 | 例 |
サーバー ID | サーバーパネル上部に表示 |
|
ホスト名 | サーバー情報 → ホスト名 |
|
操作対象のドメイン | ドメイン設定 → ドメイン一覧 |
|
ドキュメントルート | ドメイン設定 → ドメイン一覧の「ドキュメントルート」列 |
|
ヒント: 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 サーバーパネルで手動で行う必要があります。
公開鍵の内容を確認:
cat ~/.ssh/xserver_<サーバーID>.pubXServer サーバーパネルにログイン
「SSH設定」 を開く
SSH 設定が 「ON」 になっていることを確認(OFF なら ON に変更)
「公開鍵登録・更新」 タブを開く
上記の公開鍵の内容を全文貼り付けて 「確認画面へ進む」 → 「登録する」
Step 6: 接続テスト
ssh -p 10022 -i ~/.ssh/xserver_<サーバーID> <サーバーID>@<サーバーID>.xsrv.jp 'pwd'Step 7: doctor で最終確認
node src/cli.js doctorすべて [PASS] になればセットアップ完了です。
トラブルシューティング
doctor の出力 | 原因 | 対処 |
| 設定ファイルが見つからないか JSON が不正 |
|
| 秘密鍵ファイルが見つからない | Step 4 の鍵作成を確認。パスが設定ファイルの |
| SSH 接続に失敗 | Step 5 の公開鍵登録を確認。 |
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]診断
コマンド | 説明 |
| 設定ファイル、SSH 鍵、SFTP 接続をチェック |
| 設定済みサーバー一覧を表示(接続不要) |
| 設定済みドメインルート一覧を表示 |
| バージョンを表示 |
ファイル操作
コマンド | 説明 |
| リモートファイル一覧 |
| リモートの UTF-8 テキストファイルを読み取り |
| リモートにファイルを書き込み(既存ファイルは自動バックアップ) |
| テキストの完全一致置換(自動バックアップ) |
| タイムスタンプ付きリモートバックアップを作成 |
| ファイルのリモートバックアップ一覧 |
| 古いバックアップを削除し、最新 N 件を保持(デフォルト 5) |
ワークスペース操作
コマンド | 説明 |
| ドメイン用のローカルワークスペースを作成 |
| リモートファイルをローカルワークスペースに取得 |
| ローカルワークスペースのファイルをサーバーに送信(自動バックアップ) |
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 ツール一覧
ツール | 説明 |
| 設定済みサーバー一覧 |
| プロファイルのドメインルート一覧 |
| ドメイン用のローカルワークスペースを作成 |
| リモートファイル一覧 |
| UTF-8 テキストファイルを読み取り |
| リモートファイルをローカルワークスペースに取得 |
| ローカルワークスペースのファイルをリモートに送信 |
| リモートファイルのタイムスタンプ付きバックアップを作成 |
| UTF-8 ファイルを書き込み(既存ファイルは自動バックアップ) |
| テキストの完全一致置換(自動バックアップ) |
|
|
複数サーバー
設定ファイルの 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.mdSFTP ファイル操作スキル:
skills/xserver-files-operator/SKILL.mdXServer パネル 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-supportsymlink が使えない環境では copy view を生成できます:
npm run agent:install -- --copy --forceAvailable Tools
13 toolsadd_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 serverARead-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 filesARead-only
List files under a configured domain root over SFTP.
Inputs: domain (required), path, server_id.
list_rootsList domain rootsARead-only
List configured domain roots for a server profile.
Inputs: server_id.
list_serversList configured XServer profilesARead-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 fileADestructive
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 fileBRead-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 fileADestructive
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 redirectADestructive
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 fileADestructive
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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
Browse and manage files in your Moxt AI workspace from any MCP client.
A MCP server built for developers enabling Git based project management with project and personal…
An MCP server for the STRG.com s3-compatible object storage network for all management operations. Full documentation access, ask questions, create buckets, configure scoped access keys, CORS rules, lifecycle policies and perform any S3 operation.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Related MCP Servers
- FlicenseBqualityDmaintenanceA lightweight MCP server for basic file operations, enabling reading, writing, and listing files securely via the Model Context Protocol.31-
- AlicenseNot gradedqualityBmaintenanceA full-featured MCP server for local development with filesystem, shell, editor, session persistence, and security features.2MIT
- AlicenseNot gradedqualityDmaintenanceSSH-based MCP server that enables remote execution of SSH commands, file transfers, and secure server management via the MCP protocol.ISC
- AlicenseBqualityCmaintenanceA secure file management MCP server enabling file operations like listing, reading, creating, renaming, moving, copying, deleting, and searching within a restricted workspace.10MIT