VS Code MCP Server

1# VS Code MCP Server
2 
3A Visual Studio Code extension (available on the [Marketplace](https://marketplace.visualstudio.com/items?itemName=JuehangQin.vscode-mcp-server)) that allows Claude and other MCP clients to code directly in VS Code! Inspired by [Serena](https://github.com/oraios/serena), but using VS Code's built-in capabilities. Perfect for extending existing coding agents like Claude Code with VS Code-specific capabilities (symbol search, document outlines) without duplicating tools they already have. Note that this extension uses the streamable HTTP API, not the SSE API.
4 
5This extension can allow for execution of shell commands. This means that there is a potential security risk, so use with caution, and ensure that you trust the MCP client that you are using and that the port is not exposed to anything. Authentication would help, but as the MCP authentication spec is still in flux, this has not been implemented for now.
6 
7PRs are welcome!
8 
9## Demo Video
10https://github.com/user-attachments/assets/20b87dfb-fc39-4710-a910-b9481dde1e90
11 
12## Installation
13 
141. Install the extension from the [Marketplace](https://marketplace.visualstudio.com/items?itemName=JuehangQin.vscode-mcp-server) or clone this repository and run `npm install` and `npm run compile` to build it.
15 
16## Claude Desktop Configuration
17 
18Claude Desktop can be configured to use this extension as an MCP server. To do this, your `claude_desktop_config.json` file should look like this:
19```
20{
21  "mcpServers": {
22    "vscode-mcp-server": {
23        "command": "npx",
24        "args": ["mcp-remote@next", "http://localhost:3000/mcp"]
25    }
26 
27  }
28}
29```
30 
31I also like to use this extension in a Claude project, as it allows me to specify additional instructions for Claude. I find the following prompt to work well:
32```
33You are working on an existing codebase, which you can access using your tools. These code tools interact with a VS Code workspace.
34 
35WORKFLOW ESSENTIALS:
361. Always start exploration with list_files_code on root directory (.) first
372. CRITICAL: Run get_diagnostics_code after EVERY set of code changes before completing tasks
383. For small edits (≤10 lines): use replace_lines_code with exact original content
394. For large changes, new files, or uncertain content: use create_file_code with overwrite=true
40 
41EXPLORATION STRATEGY:
42- Start: list_files_code with path='.' (never recursive on root)
43- Understand structure: read key files like package.json, README, main entry points
44- Find symbols: use search_symbols_code for functions/classes, get_document_symbols_code for file overviews
45- Before editing: read_file_code the target file to understand current content
46 
47EDITING BEST PRACTICES:
48- Small modifications: replace_lines_code (requires exact original content match)
49- If replace_lines_code fails: read_file_code the target lines, then retry with correct content
50- Large changes: create_file_code with overwrite=true is more reliable
51- After any changes: get_diagnostics_code to check for errors
52 
53PLANNING REQUIREMENTS:
54Before making code modifications, present a comprehensive plan including:
55- Confidence level (1-10) and reasoning
56- Specific tools you'll use and why
57- Files you'll modify and approach (small edits vs complete rewrites)
58- How you'll verify the changes work (diagnostics, testing, etc.)
59 
60ERROR HANDLING:
61- Let errors happen naturally - don't add unnecessary try/catch blocks
62- For tool failures: follow the specific recovery guidance in each tool's description
63- If uncertain about file content: use read_file_code to verify before making changes
64 
65APPROVAL PROCESS:
66IMPORTANT: Only run code modification tools after presenting a plan and receiving explicit approval. Each change requires separate approval.
67 
68Do not add tests unless specifically requested. If you believe testing is important, explain why and let the user decide.
69```
70 
71For context efficiency when exploring codebases, consider adding this to your CLAUDE.md:
72```
73## VS Code Symbol Tools for Context Efficiency
74Use VS Code symbol tools to reduce context consumption:
75- `get_document_symbols_code` for file structure overview instead of reading entire files
76- `search_symbols_code` to find symbols by name across the project
77- `get_symbol_definition_code` for type info and docs without full file context
78- Workflow: get outline → search symbols → get definitions → read implementation only when needed
79```
80 
81 
82 
83This extension serves as a Model Context Protocol (MCP) server, exposing VS Code's filesystem and editing capabilities to MCP clients.
84 
85## Features
86 
87The VS Code MCP Server extension implements an MCP-compliant server that allows AI models and other MCP clients to:
88 
89- **List files and directories** in your VS Code workspace
90- **Read file contents** with encoding support and size limits
91- **Move files and directories** with proper refactoring support for imports
92- **Rename files and directories** with automatic reference updates
93- **Copy files** to new locations (files only, not directories)
94- **Search for symbols** across your workspace
95- **Get symbol definitions** and hover information by line and symbol name
96- **Create new files** using VS Code's WorkspaceEdit API
97- **Make line replacements** in files
98- **Check for diagnostics** (errors and warnings) in your workspace
99- **Execute shell commands** in the integrated terminal with shell integration
100- **Toggle the server** on and off via a status bar item
101 
102This extension enables AI assistants and other tools to interact with your VS Code workspace through the standardized MCP protocol.
103 
104## How It Works
105 
106The extension creates an MCP server that:
107 
1081. Runs locally on a configurable port (when enabled)
1092. Handles MCP protocol requests via HTTP
1103. Exposes VS Code's functionality as MCP tools
1114. Provides a status bar indicator showing server status, which can be clicked to toggle the server on/off
112 
113## Supported MCP Tools
114 
115### File Tools
116- **list_files_code**: Lists files and directories in your workspace
117  - Parameters:
118    - `path`: The path to list files from
119    - `recursive` (optional): Whether to list files recursively
120 
121- **read_file_code**: Reads file contents
122  - Parameters:
123    - `path`: The path to the file to read
124    - `encoding` (optional): File encoding (default: utf-8)
125    - `maxCharacters` (optional): Maximum character count (default: 100,000)
126 
127- **move_file_code**: Moves a file or directory to a new location using VS Code's WorkspaceEdit API
128  - Parameters:
129    - `sourcePath`: The current path of the file or directory to move
130    - `targetPath`: The new path where the file or directory should be moved to
131    - `overwrite` (optional): Whether to overwrite if target already exists (default: false)
132 
133- **rename_file_code**: Renames a file or directory using VS Code's WorkspaceEdit API
134  - Parameters:
135    - `filePath`: The current path of the file or directory to rename
136    - `newName`: The new name for the file or directory
137    - `overwrite` (optional): Whether to overwrite if a file with the new name already exists (default: false)
138 
139- **copy_file_code**: Copies a file to a new location using VS Code's file system API
140  - Parameters:
141    - `sourcePath`: The path of the file to copy
142    - `targetPath`: The path where the copy should be created
143    - `overwrite` (optional): Whether to overwrite if target already exists (default: false)
144 
145### Edit Tools
146- **create_file_code**: Creates a new file using VS Code's WorkspaceEdit API
147  - Parameters:
148    - `path`: The path to the file to create
149    - `content`: The content to write to the file
150    - `overwrite` (optional): Whether to overwrite if the file exists (default: false)
151    - `ignoreIfExists` (optional): Whether to ignore if the file exists (default: false)
152 
153- **replace_lines_code**: Replaces specific lines in a file
154  - Parameters:
155    - `path`: The path to the file to modify
156    - `startLine`: The start line number (1-based, inclusive)
157    - `endLine`: The end line number (1-based, inclusive)
158    - `content`: The new content to replace the lines with
159    - `originalCode`: The original code for validation
160 
161### Diagnostics Tools
162- **get_diagnostics_code**: Checks for warnings and errors in your workspace
163  - Parameters:
164    - `path` (optional): File path to check (if not provided, checks the entire workspace)
165    - `severities` (optional): Array of severity levels to include (0=Error, 1=Warning, 2=Information, 3=Hint). Default: [0, 1]
166    - `format` (optional): Output format ('text' or 'json'). Default: 'text'
167    - `includeSource` (optional): Whether to include the diagnostic source. Default: true
168 
169  This tool is particularly useful for:
170  - Code quality checks before committing changes
171  - Verifying fixes resolved all reported issues
172  - Identifying problems in specific files or the entire workspace
173 
174### Symbol Tools
175- **search_symbols_code**: Searches for symbols across the workspace
176  - Parameters:
177    - `query`: The search query for symbol names
178    - `maxResults` (optional): Maximum number of results to return (default: 10)
179  
180  This tool is useful for:
181  - Finding definitions of symbols (functions, classes, variables, etc.) across the codebase
182  - Exploring project structure and organization
183  - Locating specific elements by name
184 
185- **get_symbol_definition_code**: Gets definition information for a symbol in a file
186  - Parameters:
187    - `path`: The path to the file containing the symbol
188    - `line`: The line number of the symbol
189    - `symbol`: The symbol name to look for on the specified line
190  
191  This tool provides:
192  - Type information, documentation, and source details for symbols
193  - Code context showing the line where the symbol appears
194  - Symbol range information
195  
196  It's particularly useful for:
197  - Understanding what a symbol represents without navigating away
198  - Checking function signatures, type definitions, or documentation
199  - Quick reference for APIs or library functions
200 
201- **get_document_symbols_code**: Gets an outline of all symbols in a file, showing the hierarchical structure
202  - Parameters:
203    - `path`: The path to the file to analyze (relative to workspace)
204    - `maxDepth` (optional): Maximum nesting depth to display
205  
206  This tool provides:
207  - Complete symbol tree for a document (similar to VS Code's Outline view)
208  - Hierarchical structure showing classes, functions, methods, variables, etc.
209  - Position information and symbol kinds for each symbol
210  - Summary statistics by symbol type
211  
212  It's particularly useful for:
213  - Understanding file structure and organization at a glance
214  - Getting an overview of all symbols in a document
215  - Analyzing code architecture and relationships
216  - Finding all symbols of specific types within a file
217 
218### Shell Tools
219- **execute_shell_command_code**: Executes a shell command in the VS Code integrated terminal with shell integration
220  - Parameters:
221    - `command`: The shell command to execute
222    - `cwd` (optional): Optional working directory for the command (default: '.')
223 
224  This tool is useful for:
225  - Running CLI commands and build operations
226  - Executing git commands
227  - Performing any shell operations that require terminal access
228  - Getting command output for analysis and further processing
229 
230## Caveats/TODO
231 
232Currently, only one workspace is supported. The extension also only works locally, to avoid exposing your VS Code instance to any network you may be connected to.
233 
234## Extension Settings
235 
236* `vscode-mcp-server.port`: The port number for the MCP server (default: 3000)
237* `vscode-mcp-server.host`: Host address for the MCP server (default: 127.0.0.1)
238* `vscode-mcp-server.defaultEnabled`: Whether the MCP server should be enabled by default on VS Code startup
239* `vscode-mcp-server.enabledTools`: Configure which tool categories are enabled (file, edit, shell, diagnostics, symbol)
240 
241**Selective Tool Configuration**: Useful for coding agents that already have certain capabilities. For example, with Claude Code you might disable file/edit tools and only enable symbol tools to add VS Code-specific symbol searching without tool duplication.
242 
243## Using with MCP Clients
244 
245To connect MCP clients to this server, configure them to use:
246```
247http://localhost:3000/mcp
248```
249 
250Or if you've configured a custom host:
251```
252http://[your-host]:3000/mcp
253```
254 
255Remember that you need to enable the server first by clicking on the status bar item!
256 
257## Contributing
258 
259Contributions are welcome! Feel free to submit issues or pull requests.
260 
261## License
262 
263[MIT](LICENSE)
264