vscode-mcp-api（VS Code MCP 桥接）

bilibili视频教程 https://www.bilibili.com/video/BV1FMeW6RE1J

用户 QQ 交流群：611067889

注意！所有能够调用 MCP 的 AI 都可以使用本插件，本插件正在持续更新中。开源不易，请点个 Star 支持。

中文 | English

本项目基于开源项目 vscode-mcp-bridge 完成。 This project is based on the open-source project vscode-mcp-bridge.

---

把正在运行的 VS Code 实例通过 MCP（Model Context Protocol）暴露给 AI 智能体：智能体可以读写文件、查看 LSP 诊断、执行终端命令、操作 git、进行重构——就像坐在你电脑前一样。

功能特性

• 27 个 MCP 工具：文件读写、可视化 Diff、LSP（诊断/定义/引用/悬停/符号）、全工作区重构、终端管理、git 状态等
• 双传输端点：/sse（本地经典 SSE）+ /mcp（Streamable HTTP 无状态，远程/代理环境推荐）
• 内置 cloudflared 外网隧道：一键把本机 VS Code 暴露到公网（trycloudflare.com），让网页版/其它电脑上的智能体接入
• 「MCP 桥接面板」：真实输入框显示当前外网地址（自动刷新），真按钮一键复制地址 / 复制关键提示词
• 可选 Bearer Token 鉴权与命令白名单，控制访问面
• 扩展随 VS Code 启动自动运行，无需手动开启

---

安装

方式一：命令行安装 VSIX

code --install-extension "vscode-mcp-api-1.0.1.vsix" --force

方式二：VS Code 界面安装

1. 打开扩展面板（Ctrl+Shift+X）
2. 点击面板右上角 ··· → 从 VSIX 安装
3. 选择 vscode-mcp-api-1.0.1.vsix
4. 重新加载窗口（Ctrl+Shift+P → “重新加载窗口”）

验证安装

窗口重载后，右下角状态栏会出现 MCP :3333 字样；也可以执行健康检查：

curl http://127.0.0.1:3333/health
# {"status":"ok","version":"1.0.1","connectedAgents":0,"port":3333}

端口默认 3333，默认「固定端口」策略：地址 http://127.0.0.1:3333 重启后保持不变。若端口被占用会给出明确报错（含占用进程），不会悄悄顺延；如需旧版顺延行为，可开启 mcpServer.portFallback。

---

使用一：本地智能体接入（同一台电脑）

给本机的 MCP 客户端（Claude Code、Cline、其它支持 MCP 的工具）配置：

配置示例（~/.claude/mcp.json 或支持 mcpServers 的客户端）：

{
  "mcpServers": {
    "vscode": {
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

配置好后对智能体说“连接 MCP 并列出可用工具”，即可看到全部 27 个工具。

使用二：远程智能体接入（网页版/其它电脑）

1. 开启外网隧道（三种方式任选）：
   • 设置中勾选 mcpServer.enableCloudflareTunnel（服务器启动时自动开启）
   • 点击状态栏「外网隧道」按钮一键开启/关闭
   • 命令面板运行「VS Code MCP 桥接：启动/停止外网隧道」
2. 首次使用需安装 cloudflared，扩展会提示 winget 自动安装或给出下载直链
3. 隧道建立后弹出通知，点击通知上的 「打开面板」 按钮
4. 在「MCP 桥接面板」中点击 「📋 复制关键提示词」，得到：

https://xxxx-xxxx-xxxx.trycloudflare.com/mcp

请你连接使用这个MCP，了解里面的可以用的工具，然后接下来所有对话都需要使用MCP里面的工具进行完成

5. 把上面内容直接粘贴给远程智能体（网页聊天、其它电脑上的模型）即可接入

⚠️ 远程必须使用 /mcp 端点。 部分网络环境（含部分 Cloudflare 隧道线路）会缓冲 SSE 长连接的正文，表现为“/sse 返回 200 但收不到 endpoint 事件”；/mcp 是无状态纯请求-响应，可正常穿透。

注意：trycloudflare 临时隧道地址在每次重启后都会变化，以「MCP 桥接面板」显示的当前地址为准。

固定公网地址（给多个用户分发时必读）

trycloudflare 快速隧道是 Cloudflare 的匿名临时隧道，子域名每次启动随机生成，代码层面无法固定。要让地址永久不变，必须使用令牌/命名隧道 + 固定域名。

给几百人分发时，不能让每个用户各自买域名或注册账号。正确做法是：由你（插件作者）持有 1 个域名 + 1 个 Cloudflare 账号，为每个用户预置一条隧道并发放令牌。

发号方（你）的一次性准备：

1. 把一个域名托管到 Cloudflare（免费版即可）
2. 在 Cloudflare Zero Trust → Networks → Tunnels 为每个用户创建一条隧道：公网主机名填 用户ID.mcp.你的域名，服务指向 http://127.0.0.1:3333
3. 复制该隧道的令牌，连同主机名一起发给对应用户

用户侧配置（令牌不写入 settings.json）：

1. 命令面板运行「VS Code MCP 桥接：设置隧道令牌」（或点面板上的 🔑 按钮），粘贴令牌 —— 保存进系统凭据库
2. 在设置里填两项：

{
  "mcpServer.tunnelHostname": "用户ID.mcp.你的域名",
  "mcpServer.enableCloudflareTunnel": true
}

批量/脚本部署可改用 mcpServer.tunnelTokenFile：把令牌写进仓库之外的文件（如 ~/.vscode-mcp/token），设置里只填这个路径，令牌同样不进 settings.json。

之后地址永远是 https://用户ID.mcp.你的域名/mcp，重启、重装都不变。

🔐 令牌安全（务必读完）

开源本身不会泄露令牌：仓库里只有设置项的名字，令牌是每个用户运行时的本地数据，不进代码、不进仓库。但下面这些才是真正的泄露途径：

为什么令牌这么敏感：拿到隧道令牌的人可以自己起一个 connector 加入这条隧道；Cloudflare 会在多个 connector 间负载均衡，于是他就能明文收到该用户的 MCP 请求（含源码、终端命令，甚至 Authorization 里的 authToken）。所以必须：一人一令牌、可单独吊销、泄露后立刻在控制台删掉该隧道并重新签发。

⚠️ 令牌隧道下公网入口由你在 Cloudflare 侧配置（指向 http://127.0.0.1:3333），因此用户应保持默认端口 3333。 📌 Cloudflare 免费版的「隧道数量」与「单域名 DNS 记录数」都有配额上限，规模上到几百人前请先在账号内实测确认。 📌 若你的用户多数只是在本机用智能体（Claude Code / Cline 等），根本不需要公网隧道：本地固定地址 http://127.0.0.1:3333/mcp 永远不变、零成本、零暴露风险。

📊 免费域名 / 隧道服务实机实测

在真实网络环境下逐个测试（DNS 解析 + TLS 握手 + HTTP 请求）：

workers.dev 的判定依据：先用 --resolve 绕过 DNS 直连真实 Cloudflare 边缘 IP，同一 IP 换 cloudflare.com SNI 返回 200，换 workers.dev SNI 立即失败 → 证明是 SNI 阻断（而非单纯 DNS 污染），所以 DoH / hosts 绕过无效。

⚖️ localtunnel 模式的风险与取舍

• ✅ 优点：零账号、零域名、免安装 cloudflared，地址固定，国内实测可用
• ⚠️ 子域名无法预留：loca.lt 是先到先得的公共资源，隧道断开后别人可能抢注。因此扩展默认自动生成不可猜测的随机子域名（mcp-，持久保存），把劫持风险降到实际不可行
• ⚠️ 第三方免费服务：无 SLA、延迟约 1–3 秒/请求、可能限流。给几百人做正式产品时，仍建议用上面的令牌隧道 + 自有域名
• 🎯 推荐定位：个人自用、快速验证，或用户确实无法获得域名时的兜底方案

🐞 已知坑（已修）：loca.lt 在请求的子域名当下不可用时（被占用，或刚重启 VS Code 时上一条隧道还没在服务端释放）不会报错，而是静默返回一个随机子域名（形如 brave-otter-12），导致"固定地址"悄悄失效。

实测数据：loca.lt 在隧道断开后约 55–60 秒才释放子域名（逐 5 秒探测：+5s…+50s 全部返回随机名，+55s 才拿回原名）。所以"刚重启就报子域名被占用"是正常现象，不是被别人抢了。

现在的行为：扩展会校验实际分配到的子域名，不一致就关掉随机隧道并每 5 秒重试、最多 18 次（约 85 秒，完整覆盖释放窗口），期间显示进度通知；仍拿不到才报错，并会探测 https://.loca.lt/health 判断占用者是谁：

• 返回本扩展的 /health → 是你自己的另一个 VS Code 窗口在占用（关掉它，或让每个窗口用不同子域名）
• 返回别的内容 → 被别人占用，换名字
• 无法访问 → 旧连接尚未超时释放，稍后再试

报错时还提供「用随机地址启动」按钮作为退路，绝不会把随机地址当成你的固定地址展示。

「MCP 桥接面板」入口

• 命令面板运行「VS Code MCP 桥接：打开管理面板」
• 点击状态栏 MCP :3333 → 「打开管理面板」
• 隧道开启通知上的「打开面板」按钮

面板内含：服务器/隧道状态、外网地址输入框（自动刷新）、「复制地址」「复制关键提示词」按钮、本地地址复制。

---

设置项

在 VS Code 设置中搜索 mcpServer：

全部命令

---

工具列表（27 个）

安全须知

• 公网隧道 + 无鉴权 = 任何拿到地址的人都能操作你的 VS Code（含执行终端命令）。强烈建议设置 mcpServer.authToken，并在远程客户端配置中携带请求头："Authorization": "Bearer "
• execute_vscode_command 默认全部禁止，仅执行 allowedCommands 白名单中的命令
• 临时隧道地址虽是随机词组，但一旦泄露给他人即等同交出控制权，请勿公开分享

常见问题

Q：远程连 /sse 返回 200，却一直收不到 endpoint 事件？ 隧道线路缓冲了 SSE 正文。远程一律改用 /mcp 端点（无状态请求-响应），本地两种端点均可。

Q：隧道地址变了，之前的地址失效？ trycloudflare 临时隧道每次启动生成新随机地址，属正常现象。打开「MCP 桥接面板」复制最新地址即可。要让地址永久固定：推荐用令牌隧道（令牌存系统凭据库 + mcpServer.tunnelHostname，用户端无需账号/域名）；也可用户自建命名隧道（mcpServer.tunnelName + mcpServer.tunnelHostname，需先在 ~/.cloudflared 完成 cloudflared tunnel login / create / route dns ）。

Q：每次启动 MCP 本地地址都不一样？ 默认端口策略是「固定端口」：始终使用 mcpServer.port（默认 3333），不再自动顺延，重启后地址保持 http://127.0.0.1:3333/…。若端口被占用导致之前地址漂移，现在会弹出明确错误（含占用进程 PID），处理占用后地址即恢复固定。

Q：如何查看运行日志？ 输出面板（Ctrl+Shift+U）选择「MCP 桥接」频道，包含服务器、隧道、工具调用的详细日志。

Q：端口被占用？ 默认固定端口：启动失败时会提示占用进程（PID），可「打开端口设置 / 复制占用信息 / 重试」。如需旧版自动顺延行为，开启 mcpServer.portFallback；/health 返回中的 port 字段是实际端口。

从源码构建

npm install
npm run typecheck                  # 类型检查
npm run build                      # esbuild 打包到 out/extension.js
npx vsce package --no-dependencies # 生成 VSIX

---

vscode-mcp-api (VS Code MCP Bridge)

中文 | English

Expose your running VS Code instance to AI agents over MCP (Model Context Protocol): agents can read and write files, inspect LSP diagnostics, run terminal commands, work with git, and refactor — as if they were sitting at your computer.

Features

• 27 MCP tools: file I/O, visual diff, LSP (diagnostics / definition / references / hover / symbols), workspace-wide refactoring, terminal management, git status and more
• Dual transport endpoints: /sse (classic SSE for local use) and /mcp (stateless Streamable HTTP, recommended for remote or proxied setups)
• Built-in Cloudflare tunnel: expose your local VS Code to the public internet (trycloudflare.com) with one click, so web-based or remote agents can connect
• MCP Bridge Panel: shows the current public URL in a real input box (auto-refreshing) with one-click buttons to copy the URL or the starter prompt
• Optional Bearer token auth and a command allowlist to control the attack surface
• Starts automatically with VS Code — no manual startup needed

---

Installation

Option 1: Install the VSIX from the command line

code --install-extension "vscode-mcp-api-1.0.1.vsix" --force

Option 2: Install from the VS Code UI

1. Open the Extensions view (Ctrl+Shift+X)
2. Click ··· in the top-right corner → Install from VSIX…
3. Select vscode-mcp-api-1.0.1.vsix
4. Reload the window (Ctrl+Shift+P → “Reload Window”)

Verify the installation

After reloading, MCP :3333 appears in the status bar. You can also run a health check:

curl http://127.0.0.1:3333/health
# {"status":"ok","version":"1.0.1","connectedAgents":0,"port":3333}

The default port is 3333. By default the port is pinned: the URL http://127.0.0.1:3333 stays stable across restarts. If the port is busy you get a clear error (with the offending process/PID) instead of a silent drift. Enable mcpServer.portFallback for the old auto-increment behavior.

---

Usage 1: Local agents (same machine)

Configure your local MCP client (Claude Code, Cline, or any MCP-capable tool):

Example config (~/.claude/mcp.json or any client supporting mcpServers):

{
  "mcpServers": {
    "vscode": {
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

Then tell the agent “connect to the MCP server and list available tools” — all 27 tools will show up.

Usage 2: Remote agents (web UI / another machine)

1. Start the public tunnel (pick one):
   • Enable mcpServer.enableCloudflareTunnel in settings (starts with the server)
   • Click the “Public Tunnel” button in the status bar
   • Run “VS Code MCP Bridge: Start/Stop Public Tunnel” from the command palette
2. On first use you need cloudflared; the extension offers automatic winget install or a direct download link
3. Once the tunnel is up, a notification appears — click “Open Panel” on it
4. In the MCP Bridge Panel, click “📋 Copy Starter Prompt”:

https://xxxx-xxxx-xxxx.trycloudflare.com/mcp

Please connect to this MCP server, learn which tools it provides, and use those MCP tools for everything in this conversation.

5. Paste that text to the remote agent (web chat, a model on another machine) and it will connect

⚠️ Always use the /mcp endpoint remotely. Some networks (including certain Cloudflare tunnel routes) buffer SSE response bodies, so /sse returns 200 but no endpoint event ever arrives. /mcp is stateless request-response and traverses fine.

Note: the temporary trycloudflare tunnel URL changes on every restart (window reload / reboot / tunnel restart). Always use the URL currently shown in the MCP Bridge Panel.

Fixed public URL (required reading when distributing to many users)

A trycloudflare quick tunnel is Cloudflare’s anonymous temporary tunnel: the subdomain is random on every start and cannot be pinned in code. A permanent URL requires a token/named tunnel + a fixed hostname.

When distributing to hundreds of users, you cannot ask every user to buy a domain or create an account. The correct model is: you (the extension author) hold one domain + one Cloudflare account, and pre-provision one tunnel per user, handing each user a token.

One-time setup on your side (the issuer):

1. Put a domain on Cloudflare (the free plan is enough)
2. In Cloudflare Zero Trust → Networks → Tunnels, create one tunnel per user: public hostname user-id.mcp.your-domain, service http://127.0.0.1:3333
3. Copy that tunnel’s token and send it to the user together with the hostname

User-side configuration (the token never goes into settings.json):

1. Run “VS Code MCP Bridge: Set Tunnel Token” from the command palette (or click the 🔑 button in the panel) and paste the token — it is stored in the OS credential store
2. Set these two settings:

{
  "mcpServer.tunnelHostname": "user-id.mcp.your-domain",
  "mcpServer.enableCloudflareTunnel": true
}

For scripted/bulk deployment use mcpServer.tunnelTokenFile instead: write the token to a file outside the repository (e.g. ~/.vscode-mcp/token) and put only that path in settings — the token still never enters settings.json.

From then on the URL is always https://user-id.mcp.your-domain/mcp — across restarts and reinstalls.

🔐 Token security (please read)

Open-sourcing does not leak tokens: the repository only contains the names of settings; a token is per-user runtime data that never enters the code or the repo. These are the real leak vectors:

Why a tunnel token is so sensitive: anyone holding it can run their own connector and join that tunnel. Cloudflare load-balances across connectors, so they can receive that user’s MCP requests in plaintext — source code, terminal commands, even the authToken header. Therefore: one token per user, individually revocable, and on any leak delete that tunnel in the dashboard and re-issue.

⚠️ In token mode the public entry is configured on your Cloudflare side (pointing at http://127.0.0.1:3333), so users should keep the default port 3333. 📌 Cloudflare’s free plan has quota limits on both the number of tunnels and DNS records per zone — verify in your account before scaling to hundreds of users. 📌 If most of your users only run agents locally (Claude Code, Cline, …), no public tunnel is needed at all: the local URL http://127.0.0.1:3333/mcp never changes and costs/exposes nothing.

📊 Measured results for free domain / tunnel services

Tested one by one on a real network (DNS + TLS handshake + HTTP request):

How workers.dev was判定 / determined: using --resolve to bypass DNS and connect straight to a real Cloudflare edge IP, the same IP returns 200 with a cloudflare.com SNI but fails instantly with a workers.dev SNI — i.e. SNI blocking, not merely DNS poisoning, so DoH/hosts workarounds do not help.

⚖️ localtunnel trade-off: zero account/domain/install and reachable, but loca.lt subdomains are first-come-first-served and cannot be reserved — hence the extension auto-generates an unguessable random subdomain by default. It is a free third-party service (no SLA, ~1–3 s per request), so for a product serving hundreds of users the token tunnel with your own domain is still the recommendation.

🐞 Known pitfall (fixed): when the requested subdomain is not currently available (taken, or the previous tunnel has not been released server-side right after a VS Code restart), loca.lt does not error — it silently returns a random subdomain (e.g. brave-otter-12), which silently breaks the “fixed address” promise.

Measured: loca.lt takes about 55–60 s to release a subdomain after the tunnel disconnects (probing every 5 s: +5 s…+50 s all returned random names, +55 s finally returned the original). So “subdomain busy right after a restart” is expected behaviour, not someone stealing your name.

Current behaviour: the extension verifies the assigned subdomain, closes a mismatched tunnel, then retries every 5 s up to 18 times (~85 s, fully covering the release window) with a progress notification, and only then fails — after probing https://.loca.lt/health to identify the holder: our own /health means it is your other VS Code window, other content means someone else, and unreachable means an old connection has not timed out yet. The error also offers a “start with a random address” fallback button, and it never presents a random address as your fixed one.

Opening the MCP Bridge Panel

• Run “VS Code MCP Bridge: Open Management Panel” from the command palette
• Click MCP :3333 in the status bar → “Open Management Panel”
• Click “Open Panel” on the tunnel notification

The panel shows server/tunnel status, the public URL (auto-refreshing), buttons to copy the URL or the starter prompt, and local URL copy.

---

Settings

Search for mcpServer in VS Code settings:

All commands

---

Tool list (27 tools)

Security notes

• Public tunnel + no auth = anyone with the URL can control your VS Code (including running terminal commands). Always set mcpServer.authToken and send the header from the remote client: "Authorization": "Bearer "
• execute_vscode_command denies everything by default; only commands in allowedCommands run
• The temporary tunnel URL is a random phrase, but leaking it means handing over control — never share it publicly

FAQ

Q: /sse returns 200 remotely but the endpoint event never arrives? The tunnel buffers the SSE body. Use the /mcp endpoint remotely (stateless request-response). Both endpoints work locally.

Q: My tunnel URL changed and the old one stopped working? Temporary tunnels (trycloudflare.com) generate a new random URL on every start. Open the MCP Bridge Panel and copy the latest one. For a permanent URL, use a token tunnel (token in the OS credential store + mcpServer.tunnelHostname — no account or domain needed on the user side), or a user-managed named tunnel (mcpServer.tunnelName + mcpServer.tunnelHostname, after cloudflared tunnel login / create / route dns ).

Q: My local MCP address changes on every startup? The default port policy is pinned: the server always uses mcpServer.port (3333) and no longer auto-increments, so http://127.0.0.1:3333/… stays stable across restarts. If the port is busy you now get a clear error with the offending PID instead of a silent address change.

Q: Where are the logs? Open the Output panel (Ctrl+Shift+U) and pick the “MCP 桥接” channel — it has detailed server, tunnel, and tool-call logs.

Q: The port is already in use? The port is pinned by default: on failure the extension reports the blocking process (PID) with actions to open the port setting / copy the details / retry. Enable mcpServer.portFallback for the old auto-increment behavior; the port field in /health shows the actual port.

Build from source

npm install
npm run typecheck                  # type check
npm run build                      # bundle to out/extension.js with esbuild
npx vsce package --no-dependencies # produce the VSIX

---

本项目基于开源项目 vscode-mcp-bridge 完成。 This project is based on the open-source project vscode-mcp-bridge.