winrm-mcp

WinRM 経由で Windows ホスト上で PowerShell および CMD コマンドを実行するための、意図的に小さな MCP サーバーです。ssh-winrm-mcp から WinRM 実行のアイデアを取り入れ、焦点を絞ったマルチホストインベントリを追加し、SSH、永続セッション、ジョブ、コマンドグループ、ファイル転送は省いています。

ツール

• winrm_test — 認証と接続を検証します。

• winrm_execute_powershell — PowerShell を実行します。

• winrm_execute_cmd — CMD を実行します。

• winrm_inventory_status、winrm_inventory_init、winrm_inventory_validate — インベントリファイルを管理します。

• winrm_host_list、winrm_host_get、winrm_host_save、winrm_host_update、winrm_host_delete — 再利用可能なホストを管理します。

各ツールはオプションの connection オブジェクトを受け付けます。その中の値はプロセス環境を上書きします:

{
  "host": "192.168.1.50",
  "username": "Administrator",
  "password_env": "MY_WINRM_PASSWORD",
  "auth": "ntlm",
  "ssl": true,
  "cert_validation": false
}

ssl は HTTPS (通常ポート 5986) と HTTP (通常ポート 5985) のどちらかを選択します。自己署名 HTTPS リスナーには cert_validation=false が必要ですが、信頼できるホストでのみ使用すべきです。

サポートされている接続フィールドは、host、username、password、password_env、port、ssl、auth、cert_validation、encryption、path、connect_timeout、read_timeout、operation_timeout です。

Related MCP server: Win MCP Server

マルチホストインベントリ

ホストは次のいずれかのインベントリスコープに保存できます:

• user (デフォルト): Linux/macOS では ${XDG_CONFIG_HOME:-~/.config}/winrm-mcp/inventory.json、Windows では対応する %APPDATA% の場所。

• project: 現在の作業ディレクトリ配下の .winrm-mcp/inventory.json。

WINRM_MCP_INVENTORY_SCOPE=user または WINRM_MCP_INVENTORY_SCOPE=project でプロセスのデフォルトを選択します。すべてのインベントリツールとホストツールは明示的な scope も受け付け、実行ツールは inventory_scope を受け付けます。プロジェクトスコープは、WINRM_MCP_PROJECT_DIR、次にランチャーの論理的な PWD、次にプロセスの作業ディレクトリを使用します。使い捨てのインベントリデータを黙って保存する代わりに、一時的な deepagents_server_* パスを拒否します。ランチャーの作業ディレクトリが目的のプロジェクトルートでない場合は、WINRM_MCP_PROJECT_DIR を設定してください。完全にカスタムなファイルは WINRM_MCP_INVENTORY_FILE を通じてサポートされています。これは、呼び出しが明示的にスコープを選択しない場合に使用されます。

プロジェクトインベントリを作成し、2 つのホストを保存します:

winrm_inventory_init(scope="project")

winrm_host_save(
  name="epv1",
  scope="project",
  settings={
    "host": "10.0.110.50",
    "username": "Administrator",
    "password_env": "EPV1_WINRM_PASSWORD",
    "auth": "ntlm",
    "ssl": true,
    "cert_validation": false
  }
)

winrm_host_save(
  name="epv2",
  scope="project",
  settings={
    "host": "10.0.110.51",
    "username": "Administrator",
    "password_env": "EPV2_WINRM_PASSWORD",
    "auth": "ntlm",
    "ssl": true,
    "cert_validation": false
  }
)

保存したホストを名前で使用します:

winrm_test(saved_host="epv1", inventory_scope="project")
winrm_execute_powershell(saved_host="epv1", inventory_scope="project", command="hostname")
winrm_execute_cmd(saved_host="epv2", inventory_scope="project", command="whoami")

オプションの connection オブジェクトは、その呼び出しにおいて保存されたホストのフィールドを上書きします。インベントリの書き込みはアトミックで、インベントリファイルは Unix 系システムでは現在のユーザーのみに制限されます (0600)。インラインのパスワードはサポートされていますが、その保護された JSON ファイル内に平文で保存されます。password_env を推奨します。

上書きが必要ない場合は connection を省略します。オプション値をテキストとしてシリアライズするエージェントとの互換性のため、connection="None"、connection="null"、および空の接続文字列は JSON の null として扱われます。

DeepAgents

DeepAgents は GitHub から直接サーバーを実行できるため、ローカルチェックアウトは不要です。DeepAgents の .deepagents/.mcp.json ファイルに次のエントリを追加してください:

{
  "winrm": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "tool",
      "run",
      "--with",
      "mcp>=1.28,<2",
      "--from",
      "git+https://github.com/bigbatmanorg/winrm-mcp.git",
      "winrm-mcp"
    ],
    "env": {
      "WINRM_MCP_HOST": "192.168.1.50",
      "WINRM_MCP_USERNAME": "Administrator",
      "WINRM_MCP_PASSWORD": "YOUR_SECRET",
      "WINRM_MCP_PORT": "5986",
      "WINRM_MCP_AUTH": "ntlm",
      "WINRM_MCP_SSL": "true",
      "WINRM_MCP_CERT_VALIDATION": "false",
      "WINRM_MCP_INVENTORY_SCOPE": "project",
      "WINRM_MCP_PROJECT_DIR": "${PWD}",
      "WINRM_MCP_CONNECT_TIMEOUT": "30",
      "WINRM_MCP_READ_TIMEOUT": "60",
      "WINRM_MCP_OPERATION_TIMEOUT": "30"
    }
  }
}

再現可能なインストールのために、リポジトリをリリースタグまたはコミットに固定します:

"git+https://github.com/bigbatmanorg/winrm-mcp.git@YOUR_TAG_OR_COMMIT"

この例では、自己署名証明書を持つ信頼された開発ホストに対して、証明書検証を無効にした HTTPS を使用しています。リスナー証明書が信頼されている場合は、WINRM_MCP_CERT_VALIDATION=true を維持してください。実際のパスワードをソース管理にコミットしないでください。WINRM_MCP_PASSWORD には通常の DeepAgents のシークレット注入ワークフローを使用してください。DeepAgents は MCP サーバーを起動する前に ${PWD} を展開します。DeepAgents 自体がプロジェクトルート以外から起動される場合は、絶対パスに置き換えてください。

インストールと実行

uv sync --extra dev
uv run pytest
uv run winrm-mcp

デフォルトのトランスポートは stdio です。クライアント設定は、すべてのツール呼び出しに資格情報を入れずに、安定した接続デフォルトを提供できます:

{
  "servers": {
    "winrm": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/home/toor/projects/winrm-mcp", "run", "winrm-mcp"],
      "env": {
        "WINRM_MCP_HOST": "192.168.1.50",
        "WINRM_MCP_USERNAME": "Administrator",
        "WINRM_MCP_PASSWORD_ENV": "MY_WINRM_PASSWORD",
        "MY_WINRM_PASSWORD": "replace-me",
        "WINRM_MCP_AUTH": "ntlm",
        "WINRM_MCP_SSL": "true",
        "WINRM_MCP_CERT_VALIDATION": "false"
      }
    }
  }
}

利用可能な環境デフォルトは接続フィールドに対応し、WINRM_MCP_ プレフィックスを使用します。サーバー設定は WINRM_MCP_TRANSPORT、WINRM_MCP_SERVER_HOST、WINRM_MCP_SERVER_PORT です。インベントリ設定は WINRM_MCP_INVENTORY_SCOPE、WINRM_MCP_PROJECT_DIR、WINRM_MCP_INVENTORY_FILE です。

Kerberos または CredSSP をサポートするには、対応するオプションのエクストラをインストールしてください:

uv sync --extra kerberos
uv sync --extra credssp