win-shell-mcp

AI ネイティブなクロスプラットフォームコマンド抽象レイヤ – MCP Server の形式で 40 個の決定論的ツールを提供し、生のシェル呼び出しを代替。統一された最小限の JSON 出力を実現し、Windows のパス/エンコーディング/引用符の違いを処理します。

なぜ

AI がシェルコマンドを呼び出すのは危険で信頼性が低い：

• クロスプラットフォームの不一致：Windows のパス区切り文字、エンコーディング（GBK）、引用符、コマンド名（del vs rm）は Unix と大きく異なる

• 出力が解析しづらい：シェルコマンドの出力形式は不定で、AI が情報を確実に抽出するのが困難

• セキュリティリスク：生のシェルではパイプ、リダイレクト、コマンドインジェクションが可能

win-shell-mcp は 40 個の決定論的ツールで一般的なシェルコマンドを代替します。各ツールは：

• 構造化された JSON パラメータを受け付け、統一された { ok: true, ...data } または { ok: false, error: { code, message } } を返す

• クロスプラットフォームで一貫した動作（Windows/macOS/Linux で同じ設定）

• 最小限の出力（デフォルトでは AI の意思決定に必要な最小限のフィールドのみ）、verbose スイッチで完全なデータを取得

• 標準エラーコード（ENOENT/EISDIR/ENOTDIR/EACCES/EINVAL/ETIMEOUT/EEXEC/EUNKNOWN/INVALID_URL/NET_TIMEOUT/NET_FAIL/PROC_NOT_FOUND/PROC_KILL_FAIL/EXEC_FAIL/EXEC_TIMEOUT/GIT_FAIL）

Related MCP server: Pare

インストール

# 全局安装
npm install -g win-shell-mcp

# 或一次性运行
npx win-shell-mcp

Node.js ≥ 18 が必要です。

クライアント設定

Claude Desktop

claude_desktop_config.json を編集します（macOS: ~/Library/Application Support/Claude/、Windows: %APPDATA%\Claude\）：

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "win-shell-mcp"
    }
  }
}

グローバルインストールしていない場合は npx を使用：

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "npx",
      "args": ["win-shell-mcp"]
    }
  }
}

汎用 MCP クライアント

Model Context Protocol に対応したクライアントは stdio 経由で接続できます：

{
  "mcpServers": {
    "win-shell-mcp": {
      "command": "win-shell-mcp",
      "transport": "stdio"
    }
  }
}

起動後、クライアントは stdio を介してサーバーと通信し、40 個すべてのツールを自動的に検出します。

ツール一覧（40 個）

ドメイン別にグループ化。各ツールは統一された出力契約を返します：成功時 { ok: true, ...data }、失敗時 { ok: false, error: { code, message } }。

system（4）

fs_read（3）

fs_write（6）

text（6）

search（3）

process（2）

shell_exec（1）

env（3）

net（4）

pkg（2）

git（6）

⚠️ セキュリティに関する注意

サンドボックスなし、フル権限。

このサーバーは、実行ユーザーの完全な権限ですべての操作を実行します。これは生のシェルと同等です。fs_rm はアクセス可能な任意のファイルを削除でき、shell_exec は任意のコマンドを実行でき、process_kill はアクセス可能な任意のプロセスを終了でき、fs_write はアクセス可能な任意のファイルを上書きできます。

信頼できる環境でのみ使用してください：

• 信頼する AI クライアントにのみ接続すること

• 共有/マルチテナント環境に公開しないこと

• 機密ディレクトリ（システムディレクトリ、ユーザーホームディレクトリ）に対する操作は事前に確認すること

• 本番環境では OS レベルの権限分離（専用の低権限アカウント、コンテナ、chroot など）と組み合わせて使用することを推奨

本プロジェクトは一切のサンドボックス、権限分離、コマンドブラックリスト、パス制限を提供しません。すべてのアクセス制御は OS の権限に依存します。

開発

# 安装依赖
npm install

# 类型检查
npm run typecheck

# 测试
npm test

# 测试（watch 模式）
npm run test:watch

# 覆盖率（阈值：lines/functions/statements ≥ 85%，branches ≥ 70%）
npm run coverage

# 构建
npm run build

# 开发模式（watch 构建）
npm run dev

ビルド成果物は dist/index.js（tsup でバンドル、ESM）。

プロジェクト構成

src/
  index.ts          # 入口：启动 stdio server
  server.ts         # MCP Server 创建与工具分发
  registry.ts       # 工具注册表（注册全部 40 个工具）
  contract/         # 输出契约与错误码
  encoding/         # 编码检测（GBK/UTF-8）
  tools/            # 40 个工具实现，按域分文件
tests/
  server.test.ts    # server 单元测试
  integration/      # 集成测试（Client + InMemoryTransport）
  tools/            # 各工具单元测试
  contract/         # 契约测试
  encoding/         # 编码测试

License

MIT