mcp交叉

零依赖跨平台MCP服务器桥，用于跨不同环境的无缝stdio通信，主要用于从WSL2中的windows访问linux MCP服务器。

概述

mcp-cross 是一个Node.js CLI工具，充当AI编码工具和MCP（模型上下文协议）服务器之间的桥梁。它处理了在不同操作系统和环境中启动MCP服务器的复杂性，并特别支持WSL（Linux的Windows子系统）场景。

发布状态

1.1.0

使用最新的dist标签全局安装： npx mcp-cross@latest
从npm运行ad-hoc： npx mcp-cross@latest -- node server.js
固定特定版本（例如。， npm install -g mcp-cross@1.0.0-beta.0)用于确定性测试环境。

主要特点

跨平台路径转换：自动将Windows路径转换为WSL路径，反之亦然
标准桥接：在主机和MCP服务器之间无缝传输stdin/stdout
环境转发：将环境变量和参数传递给MCP服务器
WSL支持：处理WSL环境中运行的Windows可执行文件
HTTP代理模式：通过环境变量扩展将stdio桥接到基于HTTP的MCP服务器
通用兼容性：适用于Claude Code CLI、VSCode扩展和桌面应用程序

安装

全球安装

npm install -g mcp-cross

本地安装

npm install mcp-cross

通过npx使用（无需安装）

您可以使用 mcp-cross 不使用npx安装它：

npx mcp-cross -- node server.js

或者直接从存储库安装：

cd mcp-cross
npm install -g .

用法

直接使用（全球安装）

mcp-cross [options]  [args...]

通过npx

npx mcp-cross [options] --  [args...]

注：使用npx时 -- 建议使用分隔符将mcp交叉选项与服务器命令分隔开。

选项

--wsl -WSL环境的桥梁（仅限Windows）
--distro -特定于目标的WSL分布
--http -HTTP代理模式：目标HTTP MCP端点URL
--header -添加自定义标题（格式：“名称：值”，可重复）
--env KEY=VALUE -为启动的服务器/HTTP代理注入环境变量（可重复）
--timeout -HTTP请求超时（默认值：60000）
--debug -启用调试日志记录
-- -分隔mcp交叉选项与服务器命令的分隔符（建议与npx一起使用）

例子

直接使用

# Launch a Node.js MCP server
mcp-cross node server.js

# Launch a Python MCP server
mcp-cross python mcp_server.py --port 3000

# Launch a Windows executable from WSL
mcp-cross "C:\Program Files\mcp-server\server.exe"

# Detailed WSL bridge example with env + config
MCP_CROSS_DEBUG=true mcp-cross "C:\Tools\MyServer\server.exe" --config beta

# Launch with environment variables
MCP_PORT=3000 mcp-cross node server.js

# Enable debug mode
mcp-cross --debug node server.js

使用npx

# Launch via npx (no installation required)
npx mcp-cross -- node server.js

# With debug mode
npx mcp-cross --debug -- python mcp_server.py

# With server arguments
npx mcp-cross -- node server.js --port 3000 --config production

# Windows executable from WSL
npx mcp-cross -- "C:\Program Files\mcp-server\server.exe"

# Windows executable from WSL with explicit beta tag
npx mcp-cross@beta -- "C:\Tools\MyServer\server.exe" --port 5005

调试模式

启用调试日志记录以排除路径转换和进程启动的故障：

MCP_CROSS_DEBUG=true mcp-cross node server.js

配置示例

克劳德代码CLI

编辑您的Claude Code配置文件(~/.config/claude/config.json 在Linux/Mac或 %APPDATA%\Claude\config.json 在Windows上）：

选项1：使用全局安装的mcp-cross

{
  "mcpServers": {
    "my-server": {
      "command": "mcp-cross",
      "args": ["node", "/path/to/your/server.js"]
    }
  }
}

选项2：使用npx（无需安装）

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcp-cross", "--", "node", "/path/to/your/server.js"]
    },
    "python-server": {
      "command": "npx",
      "args": ["mcp-cross", "--", "python", "/path/to/server.py"]
    }
  }
}

带克劳德代码扩展的VSCode（WSL场景）

在WSL隧道中运行VSCode但MCP服务器在Windows上时：

VSCode：使用全局安装的mcp交叉

{
  "mcpServers": {
    "windows-server": {
      "command": "mcp-cross",
      "args": ["C:\\Program Files\\MyServer\\server.exe"]
    },
    "wsl-server": {
      "command": "mcp-cross",
      "args": ["node", "/mnt/c/projects/mcp-server/index.js"]
    },
    "node-server-with-args": {
      "command": "mcp-cross",
      "args": ["node", "/home/user/mcp-servers/my-server.js", "--config", "production"]
    }
  }
}

VSCode：使用npx（无需安装）

{
  "mcpServers": {
    "windows-server": {
      "command": "npx",
      "args": ["mcp-cross", "--", "C:\\Program Files\\MyServer\\server.exe"]
    },
    "wsl-server": {
      "command": "npx",
      "args": ["mcp-cross", "--", "node", "/mnt/c/projects/mcp-server/index.js"]
    },
    "node-server-with-args": {
      "command": "npx",
      "args": ["mcp-cross", "--", "node", "/home/user/mcp-servers/my-server.js", "--config", "production"]
    }
  }
}

克劳德代码桌面

在Claude Desktop配置中：

Claude Desktop：使用全局安装的mcp cross

{
  "mcpServers": {
    "filesystem": {
      "command": "mcp-cross",
      "args": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    },
    "custom-server": {
      "command": "mcp-cross",
      "args": ["python", "/path/to/custom_server.py"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop：使用npx（无需安装）

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["mcp-cross", "--", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Desktop"]
    },
    "custom-server": {
      "command": "npx",
      "args": ["mcp-cross", "--", "python", "/path/to/custom_server.py"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Cline（VSCode扩展）

在VSCode设置中或 .vscode/settings.json:

Cline：使用全球安装的mcp-cross

{
  "cline.mcpServers": {
    "my-server": {
      "command": "mcp-cross",
      "args": ["node", "path/to/server.js"]
    }
  }
}

临床：使用npx（无需安装）

{
  "cline.mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["mcp-cross", "--", "node", "path/to/server.js"]
    }
  }
}

Windows到WSL桥

mcp-cross 支持直接从Windows启动位于WSL中的MCP服务器。当您的开发环境和工具位于WSL中，但您使用的是基于Windows的客户端（如Windows上的Claude Desktop或VS Code）时，这很有用。

HTTP代理模式

mcp-cross 可以充当stdio到HTTP代理，允许您通过stdio接口访问基于HTTP的MCP服务器（如GitHub的MCP）。当身份验证令牌存储在WSL中，但MCP客户端在Windows上运行时，这尤其有用。

问题

当您的HTTP MCP服务器需要身份验证时：

{
  "github-mcp-server": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/",
    "headers": {
      "Authorization": "Bearer $GH_TOKEN"
    }
  }
}

如果 $GH_TOKEN 存储在WSL中（例如 ~/.bashrc)，Windows MCP客户端无法访问它。

解决方案

使用 mcp-cross 随着 --wsl --http 通过WSL代理：

{
  "github-mcp-server": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "mcp-cross@beta",
      "--wsl",
      "--http", "https://api.githubcopilot.com/mcp/",
      "--header", "Authorization: Bearer $GH_TOKEN"
    ]
  }
}

代理在WSL中运行，其中 $GH_TOKEN 可访问，扩展环境变量，并将请求转发到HTTP端点。

HTTP代理示例

# Basic HTTP proxy
mcp-cross --http https://api.example.com/mcp

# With authentication header (environment variable expanded)
mcp-cross --http https://api.example.com/mcp --header "Authorization: Bearer $TOKEN"

# Via WSL for secret access (primary use case)
mcp-cross --wsl --http https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer $GH_TOKEN"

# Multiple headers
mcp-cross --http https://api.example.com/mcp \
  --header "Authorization: Bearer $TOKEN" \
  --header "X-Tenant-ID: $TENANT_ID"

# Custom timeout
mcp-cross --http https://api.example.com/mcp --timeout 30000

# Debug mode
mcp-cross --debug --http https://api.example.com/mcp

传递环境变量

使用 --env KEY=VALUE 在不编辑Windows环境的情况下注入变量。这些值通过WSL转发（通过 WSLENV)并且可供HTTP代理用于报头扩展。

# WSL server with Linux-specific paths defined inline
mcp-cross --wsl --env GHOSTIS_STORAGE_DIR=/home/username/.ghostis/memory -- \
  python3 -m ghostis.mcp

# HTTP proxy that pulls a token from a secret manager
GH_TOKEN=$(pass show gh/token)
mcp-cross --http https://api.example.com/mcp --env GH_TOKEN=$GH_TOKEN \
  --header "Authorization: Bearer $GH_TOKEN"

HTTP代理架构

Claude Desktop (Windows)
        │
        │ stdio (JSON-RPC)
        ▼
   mcp-cross --wsl --http
   (runs in WSL via wsl.exe)
        │
        │ reads $GH_TOKEN from WSL env
        │
        │ HTTP POST (JSON-RPC)
        ▼
GitHub MCP Server (api.githubcopilot.com)

HTTP代理功能

环境变量扩展: $VAR 和 ${VAR} 标头值中的语法
会话管理：自动处理 Mcp-Session-Id 标头
错误处理：HTTP错误转换为JSON-RPC错误响应
平滑关闭：SIGINT/SIGTERM上的清理会话
安全：非本地主机HTTP警告（建议使用HTTPS）

克劳德桌面服务器食谱

在镜像Claude Desktop的配置时使用这些经过测试的命令行。每个代码段都列出了服务器在Windows下成功启动所必须存在的每个标志→ WSL桥接。

1.幽灵大脑（Python+WSL）

要求：

--wsl --shell zsh 因此，该命令在默认WSL发行版中使用与Claude相同的shell执行。
-- 实际服务器命令前的分隔符(python3 -m ghostis.mcp).
环境变量 GHOSTIS_STORAGE_DIR 和 GHOSTIS_LOG_LEVEL。要么在WSL中导出它们，要么通过重复的方式提供它们 --env KEY=VALUE 旗帜。

# Run locally (same as Claude) using the repo checkout
node . --wsl --shell zsh \
  --env GHOSTIS_STORAGE_DIR=/home/username/.ghostis/memory \
  --env GHOSTIS_LOG_LEVEL=info \
  -- python3 -m ghostis.mcp

Claude配置片段：

"ghostis-brain": {
  "command": "npx",
  "args": [
    "-y", "mcp-cross@latest",
    "--wsl", "--shell", "zsh",
    "--", "python3", "-m", "ghostis.mcp"
  ],
  "env": {
    "GHOSTIS_STORAGE_DIR": "/home/username/.ghostis/memory",
    "GHOSTIS_LOG_LEVEL": "info"
  }
}

2.文件系统服务器（节点+npx）

要求：

npx 必须存在于WSL内部。在那里安装Node/npm(sudo apt install nodejs npm)如果Windows上只有Node。
源路径是Windows目录（例如。， C:\Users\username\dev). mcp-cross 将其转换为 /mnt/c/... 为你。
目标路径是您希望MCP服务器公开的WSL挂载点（例如。， /mnt/dev/workspaces).

node . --wsl --shell zsh -- \
  npx -y @modelcontextprotocol/server-filesystem \
  "C:\\Users\\username\\dev" \
  "/mnt/dev/workspaces"

Claude配置片段：

"filesystem": {
  "command": "npx",
  "args": [
    "-y", "mcp-cross@latest",
    "--wsl", "--shell", "zsh",
    "--",
    "npx", "-y", "@modelcontextprotocol/server-filesystem",
    "C:\\Users\\username\\dev",
    "/mnt/dev/workspaces"
  ]
}

3.GitHub MCP服务器（HTTP代理）

要求：

--http https://api.githubcopilot.com/mcp/ 随着 --wsl 因此代理在Linux中运行，其中 $GH_TOKEN 生活。
传递标题 单引号 ('Authorization: Bearer $GH_TOKEN')因此PowerShell不会扩展 $GH_TOKEN 之前 mcp-cross 可以在WSL内部替换它。
确保 GH_TOKEN 存在于WSL环境中，或通过传递 --env GH_TOKEN=....

node . --wsl --shell zsh --debug \
  --env GH_TOKEN="$GH_TOKEN" \
  --http https://api.githubcopilot.com/mcp/ \
  --header 'Authorization: Bearer $GH_TOKEN'

Claude配置片段：

"github-mcp-server": {
  "command": "npx",
  "args": [
    "-y", "mcp-cross@latest",
    "--debug",
    "--wsl", "--shell", "zsh",
    "--http", "https://api.githubcopilot.com/mcp/",
    "--header", "Authorization: Bearer $GH_TOKEN"
  ]
}

提示： 从Windows PowerShell进行测试时，请保留 $GH_TOKEN 在单引号内插入文字，并将实际值传递给 --env GH_TOKEN=$env:GH_TOKEN 因此代理可以像Claude一样在WSL内扩展它。

桥梁使用

使用 --wsl 标志，指示目标服务器位于WSL中。

# Launch a Node.js server in the default WSL distro
mcp-cross --wsl node /home/user/server.js

# Launch in a specific distro
mcp-cross --wsl --distro Ubuntu-20.04 node /home/user/server.js

自动路径转换

使用时 --wsl, mcp-cross 自动将参数中的Windows文件路径转换为WSL等效路径。

# Windows path C:\data.txt becomes /mnt/c/data.txt in WSL
mcp-cross --wsl cat C:\data.txt

配置示例（Windows上的Claude桌面）

{
  "mcpServers": {
    "wsl-server": {
      "command": "npx",
      "args": [
        "mcp-cross",
        "--wsl",
        "node",
        "/home/user/server.js"
      ]
    }
  }
}

运作原理

指令分解: mcp-cross 接收MCP服务器命令和参数
路径转换:

- WSL->Windows：如果在WSL中运行，则使用以下命令将Windows路径转换为WSL路径 wslpath - Windows->WSL：如果在Windows上运行 --wsl，Windows路径转换为 /mnt/c/... 格式

繁殖过程：MCP服务器作为子进程生成（或 wsl.exe 子进程）
Stdio桥接：无缝管道stdin/stdout/stderr
信号处理：将信号/信号传递给子进程

WSL特定场景

场景1:WSL隧道中的VSCode+Windows上WSL+MCP服务器中的Claude代码

这是主要用例。什么时候：

VSCode正在通过远程WSL运行
Claude Code扩展在WSL中运行
您的MCP服务器可执行文件位于Windows上（例如。， C:\Program Files\...)

场景1：使用全局安装的mcp-cross进行配置

{
  "mcpServers": {
    "windows-mcp": {
      "command": "mcp-cross",
      "args": ["C:\\Tools\\mcp-server.exe"]
    }
  }
}

场景1：使用npx进行配置

{
  "mcpServers": {
    "windows-mcp": {
      "command": "npx",
      "args": ["mcp-cross", "--", "C:\\Tools\\mcp-server.exe"]
    }
  }
}

mcp-cross 将：

检测WSL环境
翻译 C:\Tools\mcp-server.exe 到 /mnt/c/Tools/mcp-server.exe
从WSL启动Windows可执行文件
桥接所有stdio通信

场景2：混合路径场景

如果您的MCP服务器需要访问Windows和WSL上的文件：

场景2：使用全局安装的mcp-cross

{
  "mcpServers": {
    "hybrid-server": {
      "command": "mcp-cross",
      "args": [
        "node",
        "/mnt/c/servers/bridge.js",
        "--windows-data",
        "C:\\Data",
        "--wsl-data",
        "/home/user/data"
      ]
    }
  }
}

场景2：使用npx

{
  "mcpServers": {
    "hybrid-server": {
      "command": "npx",
      "args": [
        "mcp-cross",
        "--",
        "node",
        "/mnt/c/servers/bridge.js",
        "--windows-data",
        "C:\\Data",
        "--wsl-data",
        "/home/user/data"
      ]
    }
  }
}

环境变量

MCP_CROSS_DEBUG：设置为 true 启用调试日志记录
所有其他环境变量都传递给MCP服务器

故障排除

服务器未启动

启用调试模式：

MCP_CROSS_DEBUG=true mcp-cross your-command

检查调试输出：

路径转换问题
命令解决问题
进程生成错误

WSL中找不到Windows可执行文件

确保：

该路径使用Windows格式（例如。， C:\...)或WSL格式（例如。， /mnt/c/...)
可执行文件存在于指定的路径中
您有执行权限

测试路径转换：

wslpath "C:\Program Files\MyApp\app.exe"

权限不足

确保可执行文件具有执行权限：

chmod +x /path/to/server

WSL中“找不到命令”（例如，node、npm）

如果您看到以下错误 zsh:1: command not found: node 或 bash: node: command not found 当使用 --wsl，这通常意味着该命令不在WSL发行版的系统PATH中。

如果您使用以下版本管理器，这很常见 nvm 或 pyenv，在交互式shell配置文件中配置PATH(.bashrc, .zshrc)但是 mcp-cross （通过 wsl.exe)在非交互式shell中运行命令。

解决：

使用绝对路径 到WSL中的可执行文件：

   mcp-cross --wsl /home/user/.nvm/versions/node/v18.0.0/bin/node server.js

*（提示：跑步 which node 在WSL内部查找此路径）*

将命令封装在登录shell中:

   mcp-cross --wsl bash -l -c "node server.js"

*（注：这可能会使引用论点复杂化）*

全局安装该工具 在WSL中（例如，通过 apt 或 brew)所以它在里面 /usr/bin 或 /bin.

发展

运行测试

npm test

项目结构

mcp-cross/
├── index.js          # Main CLI entry point and bridge logic
├── package.json      # NPM package configuration
├── README.md         # This file
└── test.js           # Test suite (coming soon)

贡献

欢迎投稿！请随时提交问题或拉取请求。

许可证

麻省理工学院

后续步骤

能够在docker隔离中运行，并通过stdio调用确定性代理工作负载

MCP Cross

快速接入

详细介绍

mcp交叉

概述

发布状态

1.1.0

主要特点

安装

全球安装

本地安装

通过npx使用（无需安装）

用法

直接使用（全球安装）

通过npx

选项

例子

直接使用

使用npx

调试模式

配置示例

克劳德代码CLI

选项1：使用全局安装的mcp-cross

选项2：使用npx（无需安装）

带克劳德代码扩展的VSCode（WSL场景）

VSCode：使用全局安装的mcp交叉

VSCode：使用npx（无需安装）

克劳德代码桌面

Claude Desktop：使用全局安装的mcp cross

Claude Desktop：使用npx（无需安装）

Cline（VSCode扩展）

Cline：使用全球安装的mcp-cross

临床：使用npx（无需安装）

Windows到WSL桥

HTTP代理模式

问题

解决方案

HTTP代理示例

传递环境变量

HTTP代理架构

HTTP代理功能

克劳德桌面服务器食谱

1.幽灵大脑（Python+WSL）

2.文件系统服务器（节点+npx）

3.GitHub MCP服务器（HTTP代理）

桥梁使用

自动路径转换

配置示例（Windows上的Claude桌面）

运作原理

WSL特定场景

场景1:WSL隧道中的VSCode+Windows上WSL+MCP服务器中的Claude代码

场景1：使用全局安装的mcp-cross进行配置

场景1：使用npx进行配置

场景2：混合路径场景

场景2：使用全局安装的mcp-cross

场景2：使用npx

环境变量

故障排除

服务器未启动

WSL中找不到Windows可执行文件

权限不足

WSL中“找不到命令”（例如，node、npm）

发展

运行测试

项目结构

贡献

许可证

后续步骤

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP