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 checkingeslint .- Code style checkingnpm 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
- Real-time: Leverage VSCode's LSP for real-time code state without executing slow commands
- Accuracy: Precise analysis based on language servers, more reliable than static analysis
- Efficiency: Significantly reduce AI coding agent wait times
- Integration: Deep integration with VSCode ecosystem, supporting multiple languages and extensions
Available Tools
VSCode MCP provides the following tools through the MCP protocol:
⚠️ Security Warning: The
execute_commandtool 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-toolsVSCODE_MCP_DISABLED_TOOLS- Same as--disable-tools
Architecture
Once installed and configured, VSCode MCP works seamlessly with MCP-compatible clients:
- VSCode Extension: Runs in your VSCode instance and provides access to LSP data
- 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.
