Installing Cursor MCP Servers in WSL for a Seamless Dev Experience

For developers who love the power of Linux tools but work on Windows, the Windows Subsystem for Linux (WSL) is a game-changer. Cursor, the AI-first code editor, can further enhance this setup by integrating with Model Control Program (MCP) servers. Running these MCP servers directly within your WSL environment keeps your development workflow clean and consolidated. This guide will walk you through configuring Cursor to use MCP servers running in WSL.

What is MCP?

MCP (Model Control Protocol) is a protocol that allows AI models, like those in Cursor, to securely interact with various tools and data sources. These tools, or “MCP servers,” can perform actions like web searches, file system operations, or even browser interactions, providing the AI with a richer context and more capabilities.

Why Run MCP Servers in WSL?

Consistency: Keep your entire development toolchain within the Linux environment you’re comfortable with.
Simplified Paths: Avoid complexities with Windows vs. Linux path translations for tools that access the file system.
Leverage Linux-specific Tools: Some MCP servers or their dependencies might work better or exclusively in a Linux environment.
Containment: Keep Node.js versions and other dependencies required by MCP servers managed within WSL, separate from your Windows system.

Prerequisites

Before you begin, ensure you have the following:

WSL Installed: A working WSL installation with a Linux distribution (e.g., Ubuntu).
Node.js and npx in WSL: Node.js and npx (which comes with npm) must be installed inside your WSL distribution.
- It’s highly recommended to use a version manager like nvm (Node Version Manager) within WSL to manage Node.js versions. This helps avoid permission issues and allows easy switching between Node.js versions.
Cursor IDE: Installed on your Windows machine.

Configuration Steps

The key to running MCP servers in WSL is to tell Cursor how to launch them using the WSL command-line interface. This is done by editing the mcp.json file.

1. Locate or Create `mcp.json`

Cursor stores its MCP server configurations in a file named mcp.json. On Windows, you can typically find this file in:

C:\\Users\\<YourUserName>\\.cursor\\mcp.json

Replace <YourUserName> with your actual Windows username. If the file or .cursor directory doesn’t exist, Cursor might create it when you first try to add an MCP server through its UI, or you might need to create it manually.

2. Understanding `mcp.json` Structure

The mcp.json file contains a JSON object, where each key under mcpServers represents a configured MCP server. Here’s a basic structure:

{
  "mcpServers": {
    "your-mcp-server-name": {
      "command": "executable_or_wsl",
      "args": ["argument1", "argument2", "command_to_run_in_wsl"],
      "enabled": true
      // Other options like "env", "workingDirectory" can also be specified
    }
  }
}

3. Core Configuration for WSL

To run an MCP server (which is typically an npx command) within WSL, you’ll configure a server entry as follows:

"command": Set this to "wsl".
"args": This will be an array. The first elements tell wsl which shell to use and to execute a command string. The final element is the command string itself.
- Example for bash: ["bash", "-c", "npx @some-mcp/package --port {{port}}"]
- Example for zsh: ["zsh", "-c", "npx @some-mcp/package --port {{port}}"]
(Note: {{port}} is a placeholder that Cursor often uses to inject a port number for the MCP server to listen on. Check the specific MCP server’s documentation if it requires a port.)

4. Handling Shell Environment (Crucial for `nvm` users)

A common issue is that when Cursor invokes wsl ... npx ..., the npx command might not be found, or it might not use the Node.js version you expect (especially if you use nvm). This is because the non-interactive shell session started by wsl might not load your full shell profile (e.g., .bashrc, .zshrc), where nvm and other PATH modifications are usually configured.

Here are two reliable solutions:

Solution A: Using a Shell Script (Recommended for Clarity)

This method involves creating a small shell script within your WSL environment that sets up the environment and then runs the npx command.

Create the Script in WSL: Open your WSL terminal and create a script, for example, ~/run_browsermcp.sh:

#!/bin/zsh
# Or use #!/bin/bash if you use bash

# Source your shell's rc file to load nvm and other environment settings
# Adjust the path to your rc file if necessary
if [ -f "$HOME/.zshrc" ]; then
  source "$HOME/.zshrc"
elif [ -f "$HOME/.bashrc" ]; then
  source "$HOME/.bashrc"
fi

# For debugging: check which npx is being used and Node version
# which npx
# node -v

# The actual npx command for your MCP server
# Replace with the specific MCP server command you need
npx @browsermcp/mcp@latest --port {{port}}

a example:

#!/bin/sh
zsh -c "source /home/vector/.zshrc && npx @browsermcp/mcp@latest"

(Note: The script directly invokes zsh -c. If using this approach, ensure the script itself is executable and the path to .zshrc is correct.)

Make the Script Executable: In your WSL terminal:
```
chmod +x ~/run_browsermcp.sh
```
(Adjust script name as needed).

Configure mcp.json: Modify your mcp.json to execute this script. If your WSL username is vector and you use zsh, and the script is at /home/vector/run_browsermcp.sh:

{
  "mcpServers": {
    "browsermcp-wsl": { // Give it a descriptive name
      "command": "wsl",
      "args": [
        "zsh", // Or "bash"
        "-c",
        "/home/vector/run_browsermcp.sh" // Full path to your script within WSL
      ],
      "enabled": true
    }
  }
}

This matches your provided mcp.json structure for browsermcp:

{
  "mcpServers": {
    "browsermcp": {
      "command": "wsl",
      "args": [
        "zsh",
        "-c",
        "/home/vector/browsermcp.sh" // Path from your example
      ]
    }
  }
}

Solution B: Directly Sourcing in mcp.json

You can try to source your rc file directly in the args. This can sometimes be less reliable depending on the complexity of your rc file, but it’s more concise if it works.

{
  "mcpServers": {
    "my-mcp-server-bash": {
      "command": "wsl",
      "args": [
        "bash",
        "-ic", // Note: -i for interactive to potentially help source rc files
        "source ~/.bashrc && npx @some-mcp/package --port {{port}}"
      ],
      "enabled": true
    },
    "my-mcp-server-zsh": {
      "command": "wsl",
      "args": [
        "zsh",
        "-ic", // Note: -i for interactive
        "source ~/.zshrc && npx @some-mcp/package --port {{port}}"
      ],
      "enabled": true
    }
  }
}

If nvm is used and the above still fails, you might need to provide the absolute path to nvm.sh and the npx executable installed by nvm:

{
  "mcpServers": {
    "my-mcp-nvm-direct": {
      "command": "wsl",
      "args": [
        "bash", // Or "zsh"
        "-c",
        // Replace /home/your_user and YOUR_NODE_VERSION appropriately
        "source /home/your_user/.nvm/nvm.sh && /home/your_user/.nvm/versions/node/vXX.YY.Z/bin/npx @some-mcp/package --port {{port}}"
      ],
      "enabled": true
    }
  }
}

To find the full path to npx after sourcing nvm.sh and selecting a Node version with nvm use, run which npx in your WSL terminal.

5. Example: Configuring a Browser Interaction MCP

Let’s use @browsermcp/mcp as an example, as it’s common.

Using Solution A (shell script ~/run_browsermcp.sh as defined before):

{
  "mcpServers": {
    "browsermcp-wsl": {
      "command": "wsl",
      "args": [
        "zsh", // Or "bash" if your script and environment use bash
        "-c",
        "/home/YOUR_WSL_USERNAME/run_browsermcp.sh" // Adjust path
      ],
      "enabled": true,
      "env": {
         // Optional: if the MCP server needs specific environment variables
         // "DEBUG": "true" 
      }
    }
  }
}

Remember to replace YOUR_WSL_USERNAME with your actual WSL username.

Verification

After saving mcp.json:

Restart Cursor or go to Cursor Settings -> Features -> MCP and click the refresh icon next to one of your servers or for all MCP servers.
A green dot next to the server name in the MCP settings indicates Cursor has successfully connected to it.
You might see a new terminal window pop up (launched by wsl). This window must remain open for the MCP server to function. This is expected behavior when running MCP servers this way.
Test the MCP server by asking Cursor to perform an action that uses it (e.g., for @browsermcp/mcp, ask it to “take a screenshot of the current browser tab” after setting up the companion browser extension).

Troubleshooting

npx: command not found or wrong Node version: This almost always means the shell environment within WSL isn’t being set up correctly.
- Double-check paths in your shell script or direct command.
- Ensure nvm is sourced correctly.
- Try adding export NVM_DIR="$HOME/.nvm" and [ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" explicitly at the start of your script or command string if using nvm.
- Verify that node and npx are indeed installed in your WSL distribution and accessible after sourcing your rc file.
MCP Server Fails to Connect (No Green Dot):
- Check the output in the WSL terminal window that pops up. It might contain error messages.
- Ensure the npx command for the MCP server is correct and includes any necessary arguments like --port {{port}}. Some MCPs might auto-assign ports if not specified.
- Firewall issues: Less common with WSL2’s networking model, but ensure Windows Firewall isn’t blocking connections to WSL.
“Blank” Terminal Window: As mentioned, a terminal window will open for each MCP server launched via wsl. This is normal. Closing it will stop the MCP server.

Conclusion

Configuring Cursor to run MCP servers within your WSL environment provides a streamlined and powerful development setup on Windows. By carefully setting up your mcp.json and ensuring your WSL shell environment is correctly sourced, you can seamlessly integrate AI capabilities into your Linux-based workflows. The shell script method (Solution A) is generally the most robust way to handle environments managed by tools like nvm.

What is MCP?#

Why Run MCP Servers in WSL?#

Prerequisites#

Configuration Steps#

1. Locate or Create mcp.json#

2. Understanding mcp.json Structure#

3. Core Configuration for WSL#

4. Handling Shell Environment (Crucial for nvm users)#

5. Example: Configuring a Browser Interaction MCP#

Verification#

Troubleshooting#

Conclusion#

Happy coding with Cursor and WSL!#