ClipToWSL MCP Server

How to use

You use ClipToWSL by configuring your MCP client to connect to the local MCP server and then invoking the clipboard tools from your editor or AI agent. The server runs as a local process that talks to a Windows clipboard reader and exposes clipboard data through the MCP protocol. You can read text from the Windows clipboard or analyze images that you have copied, with the option to let the client request the best available format automatically or force a specific format.

How to install

Prerequisites you need before installation are: a Windows system with WSL enabled, a Ubuntu/Debian-based WSL distribution, Node.js 18 or newer, and a TypeScript toolchain for development. If you plan to build from source, you also need a MinGW-w64 cross-compiler to build the Windows clipboard reader.

Option 1 — Quick Install (recommended)

# 1. Download and extract the release package
wget https://github.com/CarlosGtrz/ClipToWslMcp/releases/download/v1.0.0/clip-to-wsl-mcp-v1.0.0.zip
unzip clip-to-wsl-mcp-v1.0.0.zip
cd clip-to-wsl-mcp-v1.0.0/

# 2. Run the automated installer
./install.sh

# 3. Follow the configuration instructions printed by the installer

Option 2 — Build from Source

# 1. Clone the repository
git clone <repository-url>
cd ClipToWslMcp

# 2. Install build dependencies
sudo apt update
sudo apt install gcc-mingw-w64-x86-64-posix g++-mingw-w64-x86-64-posix
npm install -g typescript

# 3. Install Node.js dependencies
cd mcp-server && npm install && cd ..

# 4. Build the project
./create-release.sh  # Creates optimized release build

Additional configuration and usage notes

To use the server with a Claude Code or other MCP client, you configure a local MCP server entry that points to the runtime index file and provides the path to the Windows clipboard reader. The server can be run from a ready-to-use release package or from a source-built setup. The runtime will read clipboard data on demand and return the appropriate data format to the client.

Environment variable you must provide: CLIPBOARD_EXE_PATH, which should point to the Windows clipboard reader executable. This path is required so the MCP server can launch the Windows-side clipboard access tool.

Configuration

Integrate with your client by adding an MCP server entry that points to the local runtime. Use one of the following if you are using a release package or a source build.

{
  "mcpServers": {
    "clip-to-wsl": {
      "command": "node",
      "args": ["/path/to/release/index.js"],
      "env": {
        "CLIPBOARD_EXE_PATH": "/path/to/release/clipreader.exe"
      }
    }
  }
}

For a source build, configure with the compiled server path and the corresponding clipboard reader path.

{
  "mcpServers": {
    "clip-to-wsl": {
      "command": "node",
      "args": ["/full/path/to/ClipToWslMcp/mcp-server/dist/index.js"],
      "env": {
        "CLIPBOARD_EXE_PATH": "/full/path/to/ClipToWslMcp/clipboard-reader/clipreader.exe"
      }
    }
  }
}

Environment variables

The following environment variable is required to run the server and access Windows clipboard data: CLIPBOARD_EXE_PATH. It must point to the Windows clipboard reader executable.

Testing and validation

Test the Windows clipboard reader directly, then test the MCP server integration locally. Use the provided test utilities or your MCP client to request clipboard data and verify the returned format matches your request.

Security considerations

The Windows clipboard reader runs with minimal privileges and clipboard data is processed locally on the same machine. Process isolation helps prevent access to the rest of the WSL environment, and input validation protects against malformed clipboard data.

Troubleshooting

If you encounter issues, verify that you are running from within WSL with access to the Windows clipboard, check that CLIPBOARD_EXE_PATH points to a valid executable, and ensure the MCP server process startup succeeds. Review logs for startup events, health checks, errors, and request/response traces to diagnose problems.

Development

Project structure includes a Windows clipboard reader and a TypeScript MCP server. Build the Windows executable with MinGW-w64, compile the TypeScript server, and create a release package for distribution. The release package bundles the runtime and documentation for easy setup.

Tools and capabilities

The system exposes a read_clipboard tool through the MCP interface, enabling the client to request clipboard content. The tool can return text data, image data encoded as Base64 PNG, or a best-available format depending on the requested parameters.

Notes

The solution supports cross-platform clipboard access, multiple content types, and robust process management with health checks. It is designed for seamless integration with Claude Code and other MCP clients that require clipboard data from Windows within a WSL context.

License

MIT License - see the license terms for details.

read_clipboard

Tool exposed by the MCP server to read clipboard contents. Can deliver text or image data, with automatic or forced formatting based on the specified format parameter.