win-shell-mcp

AI-native cross-platform command abstraction layer — provides 40 deterministic tools as an MCP Server, replacing bare shell calls with unified minimal JSON output, handling Windows path/encoding/quoting differences.

Why

Letting AI call shell commands is dangerous and unreliable:

• Cross-platform inconsistency: Windows path separators, encoding (GBK), quoting, and command names (del vs rm) differ greatly from Unix

• Output hard to parse: Shell command output formats are arbitrary, making it difficult for AI to reliably extract information

• Security risk: Bare shell allows pipes, redirection, and command injection

win-shell-mcp replaces common shell commands with 40 deterministic tools, each of which:

• Accepts structured JSON parameters and returns unified { ok: true, ...data } or { ok: false, error: { code, message } }

• Behaves consistently across platforms (same configuration for Windows/macOS/Linux)

• Provides minimal output (default only includes the minimum fields needed for AI decision-making), with a verbose switch for full data

• Uses standard error codes (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

Installation

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

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

Requires Node.js ≥ 18.

Client Configuration

Claude Desktop

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

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

If not installed globally, use npx:

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

Generic MCP Client

Any client compatible with the Model Context Protocol can connect via stdio:

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

After startup, the client communicates with the server via stdio and automatically discovers all 40 tools.

Tool List (40)

Grouped by domain. Each tool returns a unified output contract: success { ok: true, ...data }, failure { 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)

⚠️ Security Note

No sandbox, full permissions.

This server performs all operations with the full permissions of the running user, equivalent to a bare shell. fs_rm can delete any accessible file, shell_exec can execute any command, process_kill can terminate any accessible process, and fs_write can overwrite any accessible file.

Only use in trusted environments:

• Only connect to AI clients you trust

• Do not expose in shared/multi-tenant environments

• Manually confirm operations on sensitive directories (system directories, user home directories)

• In production, it is recommended to use OS-level permission isolation (dedicated low-privilege accounts, containers, chroot, etc.)

This project does not provide any sandbox, permission isolation, command blacklist, or path restrictions. All access control relies on OS permissions.

Development

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

The build output is dist/index.js (bundled with tsup, ESM).

Project Structure

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