XServer Server

English | 日本語

CI CodeQL npm version License: MIT Node

Xserver 公式の サーバーパネル REST API (https://api.xserver.ne.jp) を MCP ツールとして公開する Node.js サーバー。

現状の対象 tag は メールアカウント / サーバー情報 / DNSレコード および複合ツール (domain_verification)。

ロードマップ

対応を予定している公式 API タグ (優先順位順・未確定):

• WordPress簡単インストール — list / install / update / delete
• Cron設定 — list / create / update / delete
• メール振り分け — list / create / delete
• FTPアカウント — list / create / update / delete
• サブドメイン / ドメイン設定 — list / create / delete (破壊的なため confirm ガード必須)
• MySQL / PHPバージョン / SSL設定 など残りのタグ

機能要望は Issue から受け付けます。

⚠ 非公式プロジェクトです 本プロジェクトは XServer / エックスサーバー (エックスサーバー株式会社 / XServer Inc.) が公式に提供・監修・承認するものではありません。XServer 社とは資本・契約関係のない個人有志による非公式 (unofficial) な OSS クライアントです。 "XServer" / "エックスサーバー" は XServer Inc. の商標・サービス名であり、本 README での言及は同社サービスに対応した API クライアントであることを説明する目的 (nominative use) に限られます。XServer Inc. のロゴ・ブランドリソースは使用していません。 本ソフトウェアの利用によって XServer アカウント・ドメイン・サーバー上のデータに生じたいかなる損害についても、著作者は責任を負いません (MIT License 参照)。XSERVER_API_KEY はユーザー自身が発行・管理するものであり、本プロジェクトが第三者に送信・収集することはありません。

提供ツール

全ツールは日本語ドメイン (IDN) をそのまま受け付け、MCP 側で Punycode に自動正規化する (src/tools/domain.ts)。書き込み系ツールのレスポンスには実際に送信された resolved_domain / resolved_mail_address が含まれる。DNS レコードの host / content はラベル・任意文字列なので変換しない。

toolset: mail

ツール	メソッド	パス
list_mail_accounts	GET	/v1/server/{sv}/mail
create_mail_account	POST	/v1/server/{sv}/mail
get_mail_account	GET	/v1/server/{sv}/mail/{mail_account}
update_mail_account	PUT	/v1/server/{sv}/mail/{mail_account}
delete_mail_account	DELETE	/v1/server/{sv}/mail/{mail_account} (confirm=true 必須)
get_mail_forwarding	GET	/v1/server/{sv}/mail/{mail_account}/forwarding
update_mail_forwarding	PUT	/v1/server/{sv}/mail/{mail_account}/forwarding

toolset: server

ツール	メソッド	パス
get_server_info	GET	/v1/server/{sv}/server-info
get_server_usage	GET	/v1/server/{sv}/server-info/usage

get_server_info のレスポンスに含まれる domain_validation_token は、新規ドメインの TXT 認証 (_xserver-verify.{domain} に xserver-verify={token}) に利用する。

toolset: dns

ツール	メソッド	パス
list_dns_records	GET	/v1/server/{sv}/dns
create_dns_record	POST	/v1/server/{sv}/dns
update_dns_record	PUT	/v1/server/{sv}/dns/{dns_id}
delete_dns_record	DELETE	/v1/server/{sv}/dns/{dns_id} (confirm=true 必須)

toolset: domain_verification (複合ツール)

ツール	概要
ensure_domain_verified	_xserver-verify.{domain} TXT レコードを現在の domain_validation_token と一致する状態に揃える。既に一致するレコードがあれば何もしない。
create_mail_account_with_verification	既存確認 → ensure_domain_verified → POST /mail (最大 verification_wait_ms ぶんリトライ) を 1 呼び出しで完遂する mail-address-creator 向け高レベルツール。

servername ({sv}) は .env の XSERVER_SERVERNAME で固定され、各ツールの引数には含まれない。

エラー応答形式

全ツールは失敗時に以下の正規化された形式を返す (MCP の isError: true 付き):

{
  "error": "XserverValidationError: 入力が不正です",
  "code": "VALIDATION_ERROR",
  "detail": {
    "status": 422,
    "body": { "error": { "code": "VALIDATION_ERROR", "message": "...", "errors": [...] } },
    "errors": ["mail_address は必須です"],
    "retry_after_seconds": 3,              // 429 のみ
    "rate_limit": { "remaining": 0 }       // 429 のみ
  }
}

code は公式仕様の BAD_REQUEST / UNAUTHORIZED / FORBIDDEN / NOT_FOUND / OPERATION_ERROR / VALIDATION_ERROR / RATE_LIMIT_EXCEEDED / INTERNAL_ERROR / BACKEND_ERROR / API_ERROR のいずれか。domain_verification の高レベルツールはこれに加えて DOMAIN_VERIFICATION_TIMEOUT / ALREADY_EXISTS を返すことがある。

前提条件

• Node.js 24 以上 (package.json の engines 準拠)
• Xserver サーバーパネルで発行した API キー
  • 発行手順: Xserver マニュアル「APIキー」 (同内容: サポートサイト版)

インストール

npm 経由 (推奨)

npm パッケージ として公開されています。ほとんどのユーザーはソースをクローンする必要はなく、MCP クライアントの設定で npx から起動できます (Claude Code / Claude Desktop での使用 参照)。

グローバルインストールして CLI として試すこともできます:

npm install -g xserver-mcp-server
XSERVER_API_KEY=xxx XSERVER_SERVERNAME=sv12345.xserver.jp xserver-mcp-server

ソースから (開発・デバッグ)

git clone https://github.com/Mink16/xserver-mcp.git
cd xserver-mcp
cp .env.example .env
# .env の XSERVER_API_KEY と XSERVER_SERVERNAME を実値に書き換える

npm ci
npm run build

.env は npx や npm install -g 経由で起動した場合は読み込まれない (CWD 依存のため)。MCP クライアントから起動するときは後述のとおり env フィールドで渡す。

環境変数

変数	必須	既定	用途
XSERVER_API_KEY	✅	—	Xserver API の Bearer トークン (サーバーパネル → API で発行)
XSERVER_SERVERNAME	✅	—	サーバー名 (例: sv12345.xserver.jp)
XSERVER_BASE_URL		https://api.xserver.ne.jp	API ベース URL (テスト差し替え用)
XSERVER_HTTP_CONCURRENCY		3	同時接続上限。プラン別上限 (スタンダード 5 / プレミアム 10 / ビジネス 20) より保守的に設定
XSERVER_HTTP_RETRY_MAX_ATTEMPTS		2	429 の総試行回数。1 でリトライ無効
XSERVER_HTTP_RETRY_MAX_WAIT_SEC		10	Retry-After がこの秒数を超えたらリトライせず即返す
ENABLE_TOOLSETS		(全有効)	有効化する toolset をカンマ区切りで指定。mail / server / dns / domain_verification

Claude Code / Claude Desktop での使用

npm 経由 (推奨)

プロジェクト側の .mcp.json もしくは claude_desktop_config.json に以下を追記:

{
  "mcpServers": {
    "xserver": {
      "command": "npx",
      "args": ["-y", "xserver-mcp-server"],
      "env": {
        "XSERVER_API_KEY": "your-api-key",
        "XSERVER_SERVERNAME": "sv12345.xserver.jp"
      }
    }
  }
}

env で指定していない他の環境変数 (XSERVER_HTTP_CONCURRENCY など) はすべて任意で、省略時は既定値が使われる。

ソースビルドから

ローカルでクローンしたもの (開発用) を呼ぶ場合:

{
  "mcpServers": {
    "xserver": {
      "command": "node",
      "args": ["/絶対パス/to/xserver-mcp/build/index.js"]
    }
  }
}

この構成では .env が CWD 基準で読み込まれるため、env フィールドを書かなくてもよい (ただし MCP クライアントによって CWD の扱いが異なるので env で明示するのが安全)。

別の MCP サーバーから子プロセスとして呼ぶ場合も同様に node <path>/build/index.js で起動する。相対パス指定時は呼び出し側の CWD を基準とする。

開発

npm run test:watch    # TDD
npm run typecheck     # tsc --noEmit
npm run dev           # tsx 直接実行 (build 不要)

OpenAPI 仕様 (開発者向けリファレンス)

Xserver 公式 API の OpenAPI 仕様 (docs/xserver-openapi.json) は著作権の都合上リポジトリに含めていない (.gitignore 済)。開発時に参照したい場合は 公式ドキュメント から取得して docs/xserver-openapi.json として配置する。ビルド・テストには不要。

MCP Inspector で動作確認

npm run build
npx @modelcontextprotocol/inspector node build/index.js

ブラウザが開くので Tools タブから各ツールを実行できる。

テスト

• Vitest。npm test で全テスト、npm run test:coverage でカバレッジ。
• global.fetch を tests/helpers/mockFetch.ts でモックし、HTTP 呼び出しの URL / method / body / ヘッダ を検証。
• 各ツールにつき 正常系 + 入力スキーマ検証 + API エラーを網羅。

コントリビュート

TDD (RED → GREEN → REFACTOR) サイクルを厳守する。手順・エージェントの使い分け・完了ゲートは .claude/rules/tdd-workflow.md を参照。PR 前のチェックリストは .claude/rules/pull-requests.md。

CLAUDE.md と .claude/ 配下 (rules/ / agents/ / skills/) は Claude Code などの LLM エージェントがこのリポジトリのコンテキストとして読み込むためのファイルで、人間の読み物としても本リポジトリの設計判断・運用ポリシーを知るのに役立つ。

バージョニング方針

変更履歴は CHANGELOG.md に Keep a Changelog 形式で記録します。

本プロジェクトは将来的に Semantic Versioning に準拠しますが、0.x の期間中は互換性を保証しません。minor バージョン間でも破壊的変更 (ツール名・入出力スキーマ・エラー code の変更等) が入る可能性があります。安定化後に 1.0.0 をリリースします。

行動規範

本プロジェクトの Issue / PR / Discussion での振る舞いは Contributor Covenant v2.1 に従います。

セキュリティ脆弱性は公開 Issue ではなく SECURITY.md の手順で非公開報告してください。

ライセンス

MIT