VSCode MCP

Overview

VSCode MCP is a comprehensive monorepo solution that enables MCP (Model Context Protocol) clients to access rich VSCode context information in real-time. This project bridges the gap between AI assistants and your development environment, providing accurate code analysis, diagnostics, and intelligent code navigation.

Design Motivation

VSCode MCP Bridge primarily serves AI IDEs (like Cursor) and AI coding agents, helping them develop and analyze code more efficiently.

Traditional AI coding agents often need to execute time-consuming commands when validating code modifications:

• tsc --noEmit - TypeScript type checking
• eslint . - Code style checking
• npm run build - Project building

These commands run slowly in large projects, severely impacting AI development efficiency. VSCode MCP Bridge provides real-time LSP (Language Server Protocol) information, allowing AI agents to:

• Get fast diagnostics (get-diagnostics) - Replace time-consuming type checking and lint commands
• Access comprehensive LSP information (get-symbol-lsp-info) - Get definition, hover, signatures, and type info in one call
• Navigate code efficiently (get-references) - Understand code structure and dependencies with usage context
• Safe file operations - Rename symbols across files with automatic import updates

Core Advantages

1. Real-time: Leverage VSCode's LSP for real-time code state without executing slow commands
2. Accuracy: Precise analysis based on language servers, more reliable than static analysis
3. Efficiency: Significantly reduce AI coding agent wait times
4. Integration: Deep integration with VSCode ecosystem, supporting multiple languages and extensions

Available Tools

VSCode MCP provides the following tools through the MCP protocol:

Tool	Description
execute_command	⚠️ Execute VSCode commands with JSON string arguments
get_symbol_lsp_info	Get comprehensive LSP info (definition, hover, signatures, etc.)
get_diagnostics	Get real-time diagnostics, replace slow tsc/eslint
get_references	Find symbol references with usage context code
health_check	Test connection to VSCode MCP Bridge extension
list_workspaces	List all available VSCode workspaces
open_files	Open multiple files with optional editor display
rename_symbol	Rename symbols across all files in workspace

⚠️ Security Warning: The execute_command tool can execute arbitrary VSCode commands and potentially trigger dangerous operations. Use with extreme caution and only with trusted AI models.

Installation

🚨 IMPORTANT: Before installing the MCP server, you must first install the VSCode MCP Bridge extension in your VSCode instance. The extension is required for the MCP server to communicate with VSCode.

Step 1: Install VSCode Extension

Install the VSCode MCP Bridge extension using ID: YuTengjing.vscode-mcp-bridge

Or search for "VSCode MCP Bridge" in the VSCode Extensions marketplace.

Step 2: Install MCP Server

Codex

Add the following configuration to your ~/.codex/config.toml:

[mcp_servers.vscode-mcp]
command = "bunx"
args = ["-y", "@vscode-mcp/vscode-mcp-server@latest"]
env = { "VSCODE_MCP_DISABLED_TOOLS" = "health_check,list_workspaces,open_files" }
startup_timeout_ms = 16_000

Claude Code

Claude Code (claude.ai/code) provides built-in MCP support. Simply run:

claude mcp add vscode-mcp -- npx -y @vscode-mcp/vscode-mcp-server@latest

This command will automatically configure the MCP server in your Claude Code environment.

Cursor

Click the button to install

Or install manually

Go to Cursor Settings -> Tools & Integrations -> New MCP Server. Name to your liking, use command type with the command npx @vscode-mcp/vscode-mcp-server@latest. You can also verify config or add command line arguments via clicking Edit.

{
  "mcpServers": {
    "vscode-mcp": {
      "command": "npx",
      "args": ["@vscode-mcp/vscode-mcp-server@latest"]
    }
  }
}

Gemini CLI

Add the following configuration to your ~/.gemini/settings.json:

{
  "mcpServers": {
    "vscode-mcp": {
      "command": "npx",
      "args": ["-y", "@vscode-mcp/vscode-mcp-server@latest"],
      "env": {},
      "includeTools": [
        "get_symbol_lsp_info",
        "get_diagnostics",
        "get_references",
        "health_check",
        "rename_symbol"
      ]
    }
  }
}

CLI (no MCP config required)

If your agent can shell out but you don't want to register an MCP server, install @vscode-mcp/vscode-mcp-cli. It exposes the same tools as the MCP server as plain subcommands, talking to the VSCode Bridge extension over the same socket.

# Run directly without install
bunx --bun @vscode-mcp/vscode-mcp-cli --help

# Or install globally
npm i -g @vscode-mcp/vscode-mcp-cli
vscode-cli --help

Subcommands

One subcommand per MCP tool, kebab-case:

vscode-cli get-diagnostics      # real-time LSP diagnostics
vscode-cli get-symbol-lsp-info  # hover / signatures / definitions
vscode-cli get-references       # references with usage context
vscode-cli rename-symbol        # workspace-wide rename
vscode-cli open-files           # open one or more files
vscode-cli execute-command      # ⚠️ run arbitrary VSCode commands
vscode-cli health-check         # ping the bridge
vscode-cli list-workspaces      # enumerate open VSCode windows

Workspace targeting

CLI defaults --workspace to process.cwd(). Override with --workspace <path> when you need to target a different open VSCode window (must match a workspace from list-workspaces).

Examples

# Diagnostics on git-modified files in the current workspace
vscode-cli get-diagnostics

# Find references to `myFunction` in src/utils.ts at line 42
vscode-cli get-references --file-path src/utils.ts --line 42 --character 10

# Open multiple files in background (no editor focus)
vscode-cli open-files --files src/a.ts src/b.ts --no-show-editor

# Target a different VSCode window
vscode-cli get-diagnostics --workspace /Users/me/other-project

The text output is byte-identical to what the MCP server returns — every flag is auto-generated from the IPC zod schema, so anything the MCP tool accepts has a --kebab-case flag here.

Tool Filtering

You can control which tools are available using command-line arguments or environment variables:

Command-line arguments:

• --enable-tools - Comma-separated list of tools to enable (whitelist mode). If specified, only these tools will be available.
• --disable-tools - Comma-separated list of tools to disable (blacklist mode). Applied after --enable-tools.

Environment variables:

• VSCODE_MCP_ENABLED_TOOLS - Same as --enable-tools
• VSCODE_MCP_DISABLED_TOOLS - Same as --disable-tools

Architecture

Once installed and configured, VSCode MCP works seamlessly with MCP-compatible clients:

1. VSCode Extension: Runs in your VSCode instance and provides access to LSP data
2. MCP Server / CLI: Translates MCP calls (or CLI subcommands) to VSCode extension requests over a per-workspace Unix socket

All tools require the workspace_path parameter to target a specific open VSCode instance. This must be the workspace folder reported by list_workspaces or the extension activation log, because each VSCode workspace gets its own socket connection. If you need diagnostics for files inside a child project or git submodule, keep workspace_path set to the open VSCode workspace root and pass child paths as tool-specific file parameters.

License

This project is licensed under the Anti 996 License.