Xserver MCP

XServer API を 読み取り専用 でラップした MCP サーバーです。Claude との会話から サーバーの状況（ディスク使用量・ドメイン・メール・cron など）を確認できます。

あなた: サーバーのディスク、あとどれくらい空いてる？
Claude: [xserver_server_status を実行]
        xs123456.xsrv.jp: 42.1 GB / 300 GB (14.0%)、ファイル数 128,430
        ドメイン 7、サブドメイン 12、メールアカウント 23、MySQL 4

重要な前提

• このサーバーは GET しか発行しません。 設定変更・削除は一切できません。
• お手元のマシンで動かす前提です。 Claude Desktop / ローカルの claude CLI に stdio で接続します。Claude Code on the web のリモートセッションからは api.xserver.ne.jp に到達できないため、そちらでは動きません。
• エンドポイントは実アカウントで検証済みです。 公式リファレンス （https://developer.xserver.ne.jp/api/server/ ）を参照できない状態で実装したため 当初は推測を含んでいましたが、npm run check による実測で確定させました。 一部は 404 で存在しないことが判明しています。下記「エンドポイントの検証状況」を参照してください。

セットアップ

必要環境: Node.js 20 以上。

git clone <このリポジトリ>
cd Xserver_MCP
npm install
npm run build

APIキーの発行

1. Xserver のサーバーパネルにログイン
2. 「アカウント」→「APIキー設定」
3. 「APIキー発行」をクリックしてキーをコピー

キーはチャットに貼らず、環境変数として渡してください。

動作確認

MCP クライアントに繋ぐ前に、接続チェックを実行します。

XSERVER_API_KEY='発行したキー' npm run check

/me の疎通、サーバー名の解決、各エンドポイントの到達性を順に確認し、 ok / miss で一覧表示します。miss になったパスは実在しない（＝推測が外れた） ということなので、公式リファレンスで正しいパスを確認してください。

Claude Desktop への登録

設定ファイル（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json、 Windows: %APPDATA%\Claude\claude_desktop_config.json）に追記します。

{
  "mcpServers": {
    "xserver": {
      "command": "node",
      "args": ["/absolute/path/to/Xserver_MCP/dist/index.js"],
      "env": {
        "XSERVER_API_KEY": "発行したキー",
        "XSERVER_SERVERNAME": "xs123456.xsrv.jp"
      }
    }
  }
}

args は絶対パスにしてください。設定後、Claude Desktop を再起動します。

ローカルの claude CLI の場合:

claude mcp add xserver \
  --env XSERVER_API_KEY='発行したキー' \
  --env XSERVER_SERVERNAME='xs123456.xsrv.jp' \
  -- node /absolute/path/to/Xserver_MCP/dist/index.js

環境変数

変数	必須	既定値	説明
XSERVER_API_KEY	✅	—	サーバーパネルで発行した APIキー
XSERVER_SERVERNAME		/me から自動解決	初期ドメイン。Xserver は <サーバーID>.xsrv.jp、Xserver ビジネスは <サーバーID>.xbiz.jp
XSERVER_API_BASE		https://api.xserver.ne.jp/v1	APIのベースURL（https 必須）
XSERVER_TIMEOUT_MS		30000	1リクエストあたりのタイムアウト

XSERVER_SERVERNAME を省略した場合、最初のツール呼び出し時に GET /me から サーバー名を取得してキャッシュします。

APIキーをコマンド行に直接書くと PowerShell の履歴ファイルに平文で残ります。 入力を伏せ字にして渡すには:

$env:XSERVER_API_KEY = [Runtime.InteropServices.Marshal]::PtrToStringBSTR([Runtime.InteropServices.Marshal]::SecureStringToBSTR((Read-Host "API key" -AsSecureString)))

提供ツール

ツール	用途
xserver_account_info	GET /me。契約種別・有効期限・サーバー名・権限種別。まずこれで疎通確認
xserver_server_status	サーバー状況。ディスク使用量・ファイル数・各種リソース件数のサマリと生JSON
xserver_list	リソース一覧（resource を指定）。domain / mail / cron / subdomain / ssl / php / mysql / ftp / dns など
xserver_get	任意パスへの GET。他のツールで届かないエンドポイント用の逃げ道
xserver_endpoints	このサーバーが把握しているエンドポイント一覧と確度を返す

xserver_list で 404 が返る場合は、xserver_endpoints で確度を確認したうえで、 公式リファレンスの正しいパスを xserver_get に渡してください。

エンドポイントの検証状況

Xserver ビジネス契約・permission_type: "read" のキーで npm run check を実行した実測結果です。

verified（200 が返る）

パス	レスポンス
/me	{service_type, expires_at, servername, permission_type}
/server/{servername}/server-info	{server_id, hostname, ip_address, os, cpu, ...}
/server/{servername}/server-info/usage	{disk: {quota_gb, used_gb, file_limit, file_count}, counts: {...}}
/server/{servername}/domain	{domains: [{domain, type, ssl, memo, is_awaiting}]}
/server/{servername}/mail	{accounts: [...]}
/server/{servername}/cron	{crons: [...], notification_email}
/server/{servername}/subdomain	{subdomains: [...]}
/server/{servername}/ssl	{ssl_list: [{id, common_name, type, expires_at, status}]}
/server/{servername}/ftp	{accounts: [...]}
/server/{servername}/dns	{records: [...]}
/server/{servername}/mail-filter	{filters: [...]}

disk.file_limit が 0 の場合は上限なしを意味します。

requires-params（422 VALIDATION_ERROR）

access-log / error-log

エンドポイントは存在しますが、domain パラメータが必須です（省略すると {"error":{"code":"VALIDATION_ERROR","message":"ドメインは必須です"}}）。

xserver_list(resource="access-log", query={ "domain": "example.com" })

domain の値は xserver_list(resource="domain") で取得できます。 npm run check は最初のドメインを自動で補って検証します。

unavailable（404 NOT_FOUND）

php / mysql / mysql-user / wordpress / mail-forward / backup

これらは xserver_list の候補から除外してあり、指定すると「このパスには存在しない」旨を 説明して返します。機能自体は別パスに存在する可能性があるため、公式リファレンスで 正しいパスを確認のうえ xserver_get を使ってください。

なお verified は上記1アカウント（Xserver ビジネス・読み取り権限）での結果です。 プランや権限が異なれば同じパスでも 403 になり得ます。

日本語メッセージが文字化けする場合

APIのエラーメッセージは UTF-8 の日本語です。Windows のコンソールは既定で cp932 のため 化けます。PowerShell で先に実行してください:

[Console]::OutputEncoding = [Text.Encoding]::UTF8

セキュリティ

• APIキーは環境変数からのみ読み込み、ログにもツールの応答にも出力しません。
• xserver_get に渡されたパスは正規化のうえ検証し、XSERVER_API_BASE と ホストが一致しない URL は拒否します（Authorization ヘッダを別ホストへ 送出させないため）。.. を含むパスも拒否します。
• HTTP メソッドは GET に固定されており、書き込み系は実装されていません。 書き込みを追加する場合は XserverClient にメソッドを足すことになりますが、 誤操作のリスクを踏まえて明示的なオプトイン（環境変数など）で ガードすることを推奨します。

開発

npm run build      # dist/ へコンパイル
npm run watch      # 差分ビルド
npm run typecheck  # 型チェックのみ
npm run check      # API 疎通チェック（要 XSERVER_API_KEY）

src/ の構成:

• config.ts — 環境変数の読み込みと検証
• client.ts — HTTPクライアント。認証・パス正規化・レート制限ヘッダ・エラー整形
• endpoints.ts — エンドポイントカタログ（確度付き）
• tools.ts — MCP ツールの定義と登録
• index.ts — stdio サーバーのエントリポイント
• check.ts — 疎通チェックCLI

実装メモ

MCP SDK は v1 系（@modelcontextprotocol/sdk@^1.30.0）を使用しています。 v2 系（@modelcontextprotocol/server@2.0.0）が 2026-07-27 にリリースされていますが、 リリース直後で各 MCP クライアントの対応状況が読めないため、広く動作実績のある v1 系を選択しました。v1 は少なくとも v2 リリースから6か月はメンテナンスされます。

ライセンス

MIT