win-shell-mcp

Capa de abstracción de comandos multiplataforma nativa para IA — ofrece 40 herramientas deterministas en forma de MCP Server, sustituye las llamadas directas al shell, unifica una salida JSON mínima y gestiona las diferencias de rutas, codificación y comillas de Windows.

Por qué

Hacer que la IA invoque comandos shell es peligroso y poco fiable:

• Incoherencia entre plataformas: los separadores de rutas, la codificación (GBK), las comillas y los nombres de comandos (del frente a rm) de Windows difieren enormemente de los de unix

• Salida difícil de parsear: el formato de salida de los comandos shell es arbitrario y a la IA le resulta difícil extraer información de forma fiable

• Riesgo de seguridad: el shell crudo permite tuberías, redirecciones e inyección de comandos

win-shell-mcp sustituye los comandos shell más comunes con 40 herramientas deterministas. Cada herramienta:

• Acepta parámetros JSON estructurados y devuelve, de forma uniforme, { ok: true, ...data } o { ok: false, error: { code, message } }

• Tiene un comportamiento coherente entre plataformas (la misma configuración en Windows/macOS/Linux)

• Ofrece una salida mínima (por defecto solo incluye los campos mínimos necesarios para que la IA decida); el modificador verbose recupera los datos completos

• Usa códigos de error estándar (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

Instalación

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

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

Requiere Node.js ≥ 18.

Configuración del cliente

Claude Desktop

Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

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

Si no está instalado de forma global, usa npx:

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

Cliente MCP genérico

Cualquier cliente compatible con Model Context Protocol puede conectarse mediante stdio:

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

Una vez iniciado, el cliente se comunicará con el servidor a través de stdio y descubrirá automáticamente las 40 herramientas.

Lista de herramientas (40)

Agrupadas por dominio. Cada herramienta devuelve un contrato de salida uniforme: éxito { ok: true, ...data }, error { 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)

⚠️ Nota de seguridad

Sin sandbox, plenos permisos.

Este servidor ejecuta todas las operaciones con los permisos completos del usuario que lo ejecuta, equivalente a un shell crudo. fs_rm puede eliminar cualquier archivo accesible, shell_exec puede ejecutar cualquier comando, process_kill puede terminar cualquier proceso accesible y fs_write puede sobrescribir cualquier archivo accesible.

Úsalo únicamente en entornos de confianza:

• Conéctalo solo a clientes de IA en los que confíes

• No lo expongas en entornos compartidos o multiinquilino

• Confirma manualmente antes de operar en directorios sensibles (directorios del sistema, directorio personal del usuario)

• En producción se recomienda combinarlo con aislamiento de permisos a nivel de sistema operativo (cuentas dedicadas con pocos privilegios, contenedores, chroot, etc.)

Este proyecto no ofrece ningún sandbox, aislamiento de permisos, lista negra de comandos ni restricciones de rutas. Todo el control de acceso depende de los permisos del sistema operativo.

Desarrollo

# 安装依赖
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

El artefacto de compilación es dist/index.js (empaquetado con tsup, ESM).

Estructura del proyecto

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/         # 编码测试

Licencia

MIT