wsl-terminal-bridge-mcp

Run commands in the Windows filesystem, on Windows terminals from WSL.

This MCP (Model Context Protocol) server provides a bridge between WSL (Windows Subsystem for Linux) and Windows PowerShell, allowing you to execute commands directly on the Windows filesystem without the performance overhead of cross-filesystem operations.

Features

• HTTP Streamable Transport: Supports HTTP with streamable transport for real-time communication
• PowerShell Execution: Execute PowerShell commands directly in Windows from WSL
• Fast File Operations: Bypass slow WSL-Windows filesystem transfer by running commands directly in Windows

Installation

From npm

npm install -g wsl-terminal-bridge-mcp

From source

git clone https://github.com/stefan-nica/wsl-terminal-bridge-mcp.git
cd wsl-terminal-bridge-mcp
npm install
npm run build

Usage

Stdio Mode (Traditional MCP)

After installing from npm:

# Start in stdio mode (default)
wsl-terminal-bridge-mcp

# Or using npx
npx wsl-terminal-bridge-mcp

From source:

npm start

Or in development mode:

npm run dev

HTTP Streamable Mode

After installing from npm:

# Start in HTTP Streamable mode on default port 3000
wsl-terminal-bridge-mcp --streamable-http

# Start in HTTP Streamable mode on custom port
wsl-terminal-bridge-mcp --streamable-http --port 8080

# Or using npx
npx wsl-terminal-bridge-mcp --streamable-http

# Or using environment variable for port
PORT=8080 wsl-terminal-bridge-mcp --streamable-http

From source:

# Using npm script
npm run start:http

# Or in development mode
npm run dev:http

By default, the HTTP server runs on port 3000. You can customize this with the --port flag or PORT environment variable.

Session Management

The HTTP Streamable mode uses the MCP protocol's built-in session management:

1. Automatic Session Creation: Sessions are created automatically during MCP initialization
2. Session Headers: Session IDs are included in response headers automatically
3. Session Validation: The transport validates session IDs for subsequent requests
4. Session Cleanup: Sessions are cleaned up automatically when clients disconnect

The MCP transport handles all session management internally - no manual session creation is required.

Tools

execute_ps

Execute a PowerShell command in Windows.

Parameters:

• command (string, required): The PowerShell command to execute
• timeout (number, optional): Timeout in milliseconds (default: 30000)
• workingDirectory (string, optional): Working directory for the command execution (WSL path, will be converted to Windows path)

Example:

{
  "name": "execute_ps",
  "arguments": {
    "command": "Get-ChildItem C:\\Users",
    "timeout": 5000,
    "workingDirectory": "/mnt/c/Users"
  }
}

Use Cases:

• Access Windows filesystem directly: Get-ChildItem C:\Users
• Run Windows-specific commands: Get-Process
• Execute batch operations on Windows files without WSL overhead
• Use Windows tools and utilities: ipconfig, netstat, etc.

jest_run_all

Run all Jest tests in Windows environment and return only essential results (pass/fail counts and error details). Uses PowerShell to execute npx jest with JSON output to minimize token usage by filtering out warnings and verbose output.

Parameters:

• workingDirectory (string, optional): Working directory for Jest execution (WSL path, will be converted to Windows path)

Example:

{
  "name": "jest_run_all",
  "arguments": {
    "workingDirectory": "/mnt/c/project"
  }
}

Output Format:

• Success: "Jest Results: X/Y tests passed - All tests passed!"
• With failures: "Jest Results: X/Y tests passed, Z failed\n\nFailed Tests:\n- Suite: Test Name\n Error: Error message"

get_cwd

Get the current working directory in Windows path format.

Parameters:

• workingDirectory (string, optional): Working directory to get (WSL path, will be converted to Windows path format)

Example:

{
  "name": "get_cwd",
  "arguments": {
    "workingDirectory": "/mnt/c/Users"
  }
}

Use Cases:

• Get the current working directory in Windows format
• Convert WSL paths to Windows paths for display or further processing

Configuration for MCP Clients

Claude Desktop (Stdio)

If installed globally from npm:

{
  "mcpServers": {
    "wsl-terminal-bridge": {
      "command": "wsl-terminal-bridge-mcp"
    }
  }
}

If using npx:

{
  "mcpServers": {
    "wsl-terminal-bridge": {
      "command": "npx",
      "args": ["wsl-terminal-bridge-mcp"]
    }
  }
}

If using from source:

{
  "mcpServers": {
    "wsl-terminal-bridge": {
      "command": "node",
      "args": ["/path/to/wsl-terminal-bridge-mcp/dist/index.js"]
    }
  }
}

HTTP Streamable Clients

Start the server in HTTP Streamable mode:

wsl-terminal-bridge-mcp --streamable-http

Then configure your MCP client to connect to:

http://localhost:3000/mcp

The MCP transport handles session management automatically - no additional configuration is needed.

Security Considerations

• This tool executes PowerShell commands with the same privileges as the user running the server
• Validate and sanitize all commands before execution
• Consider implementing authentication for HTTP Streamable mode in production environments
• Be cautious with commands that modify system state

Development

# Install dependencies
npm install

# Run in development mode (stdio)
npm run dev

# Run in development mode (HTTP)
npm run dev:http

# Build
npm run build

# Run built version
npm start

Adding New Tools

The server is designed to be easily extensible. Each tool lives in its own file under the src/tools/ directory.

To add a new tool:

1. Create a new tool file in src/tools/your-tool-name.ts:

import { z } from "zod";
import { MCPTool } from "./types.js";

// Define your tool's argument schema
const YourToolArgsSchema = z.object({
  param1: z.string().describe("Description of param1"),
  param2: z.number().optional().describe("Optional parameter"),
});

// Implement the handler function
async function yourToolHandler(args: z.infer<typeof YourToolArgsSchema>): Promise<string> {
  // Your tool logic here
  return `Result: ${args.param1}`;
}

// Define the tool
export const yourTool: MCPTool = {
  definition: {
    name: "your_tool_name",
    description: "Description of what your tool does",
    inputSchema: {
      type: "object",
      properties: {
        param1: {
          type: "string",
          description: "Description of param1",
        },
        param2: {
          type: "number",
          description: "Optional parameter",
        },
      },
      required: ["param1"],
    },
  },
  argsSchema: YourToolArgsSchema,
  handler: yourToolHandler,
};

2. Register the tool in src/tools/index.ts:

import { yourTool } from "./your-tool-name.js";

// Register the new tool
toolRegistry.register(yourTool);

// Export it for external use if needed
export { yourTool };

3. That's it! The tool will automatically be available to MCP clients.

See src/tools/execute-ps.ts and src/tools/get-cwd.ts for complete examples.

License

ISC