VSCode Automation MCP Server
A Model Context Protocol (MCP) server that enables AI agents to automate and control VSCode: give your AI assistant the ability to interact with the VSCode UI, execute commands, inspect the DOM, read editor content, and perform complex automation workflows.
Built on top of vscode-extension-tester, this mcp server is ideal for:
- AI-assisted VSCode extension development - Let AI agents test and interact with your extensions
- Automated UI testing - Build automation scripts driven by AI
- Development workflow automation - Automate repetitive VSCode tasks
- Extension debugging - Inspect UI state, DOM structure, and diagnostics
🚀 Features
- DOM Inspection - Get the full DOM structure, UI regions, and accessibility tree for AI understanding
- Execute VSCode Commands - Run any command from the Command Palette programmatically
- UI Automation - Click elements, type text, navigate the UI
- Keyboard Input - Press key combinations, shortcuts, and special keys
- File Operations - Open files at specific lines and columns
- Screenshots - Capture the VSCode window for debugging and verification
- Element Inspection - Get detailed information about UI elements
- Element Queries - Find multiple elements matching selectors with attributes
- JavaScript Execution - Run arbitrary JS in the VSCode window (like DevTools console)
- Diagnostics - Access errors and warnings from the Problems panel
- Editor Content - Read and verify editor content
- Webview Support - Interact with extension webviews
- Wait & Synchronization - Wait for elements, text, or idle state
- Notifications - Get, dismiss, and handle notifications
- Dialogs - Handle InputBox, QuickPick, and confirmation dialogs
- IntelliSense - Trigger completions, get items, select suggestions
- Code Navigation - Go to definition, hover tooltips, signature help
- Context Menus - Open and interact with context menus
- Output Channels - Read from VSCode output channels and extension logs
- Console Logs - Capture and filter browser console logs
- Performance Metrics - Memory usage, DOM stats, timing info
📋 Requirements
- Node.js >= 18.0.0
- Internet connection (for first run to download VSCode and ChromeDriver)
Note: The server automatically downloads a standalone VSCode instance and matching ChromeDriver on first run. It does NOT use your installed VSCode - this ensures consistent behavior and prevents conflicts with your main VSCode instance.
📦 Installation
Quick Start (Recommended)
No installation required! Just add to your MCP client configuration:
{
"mcpServers": {
"vscode-automation": {
"command": "npx",
"args": ["-y", "vscode-automation-mcp@latest"]
}
}
}
Global Installation
npm install -g vscode-automation-mcp@latest
Then run directly:
vscode-automation-mcp
From Source
git clone https://github.com/sukarth/vscode-automation-mcp.git
cd vscode-automation-mcp
npm install
npm run build
npm start
⚙️ Configuration
Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"vscode-automation": {
"command": "npx",
"args": ["-y", "vscode-automation-mcp@latest"]
}
}
}
Or if installed globally:
{
"mcpServers": {
"vscode-automation": {
"command": "vscode-automation-mcp"
}
}
}
VSCode (GitHub Copilot / Copilot Chat)
Add to your VSCode settings.json or .vscode/mcp.json:
{
"mcp": {
"servers": {
"vscode-automation": {
"command": "npx",
"args": ["-y", "vscode-automation-mcp@latest"]
}
}
}
}
Cursor
Add to Cursor's MCP configuration:
{
"mcpServers": {
"vscode-automation": {
"command": "npx",
"args": ["-y", "vscode-automation-mcp@latest"]
}
}
}
Environment Variables
You can customize the server behavior using environment variables:
| Variable | Description | Default |
|---|---|---|
VSCODE_AUTOMATION_VERSION | VSCode version to download (e.g., 1.95.0, 1.85.0, or latest) | latest |
VSCODE_AUTOMATION_STORAGE_PATH | Directory to store VSCode and ChromeDriver | System temp dir |
VSCODE_AUTOMATION_OFFLINE | Set to true to use cached binaries only | false |
VSCODE_AUTOMATION_LOG_LEVEL | Log level: trace, debug, info, warn, error | info |
Example with environment variables:
{
"mcpServers": {
"vscode-automation": {
"command": "npx",
"args": ["-y", "vscode-automation-mcp@latest"],
"env": {
"VSCODE_AUTOMATION_VERSION": "1.95.0",
"VSCODE_AUTOMATION_STORAGE_PATH": "/path/to/storage"
}
}
}
}
ChromeDriver Compatibility: The server automatically downloads the correct ChromeDriver version that matches the VSCode/Electron version. You don't need to manage ChromeDriver manually.
🛠️ Available Tools
Command Tools
| Tool | Description |
|---|---|
vscode_execute_command | Execute any VSCode command with optional arguments |
vscode_list_commands | List available VSCode commands with optional filter |
UI Action Tools
| Tool | Description |
|---|---|
vscode_click_element | Click a UI element by CSS/XPath/accessibility selector |
vscode_type_text | Type text into an input field or focused element |
vscode_open_file | Open a file in the editor at a specific line/column |
Inspection Tools
| Tool | Description |
|---|---|
vscode_take_screenshot | Capture a screenshot of the VSCode window |
vscode_get_element | Get properties and text of a UI element |
vscode_open_webview | Open an extension's webview panel |
vscode_get_diagnostics | Get all diagnostic messages from Problems panel |
DOM Inspection Tools
| Tool | Description |
|---|---|
vscode_get_dom | Get the full DOM structure of VSCode in tree, HTML, or JSON format |
vscode_get_ui_structure | Get structure of specific UI regions (sidebar, editor, panel, etc.) |
vscode_query_elements | Find all elements matching a CSS selector with attributes |
vscode_get_accessibility_tree | Get the semantic accessibility tree with ARIA roles and labels |
DOM Navigation Tools
| Tool | Description |
|---|---|
vscode_get_element_children | Get direct children or descendants of an element for incremental exploration |
vscode_get_element_parents | Get the parent chain (ancestors) of an element |
vscode_get_element_siblings | Get sibling elements at the same level |
vscode_find_interactive_elements | Find all buttons, inputs, links, tabs within a container |
vscode_search_dom | Search DOM by text, ID, class, aria-label, title, or role |
vscode_dump_dom_to_file | Dump full DOM to a file for incremental exploration by AI |
JavaScript Execution & DOM Query Tools
| Tool | Description |
|---|---|
vscode_execute_script | Execute arbitrary JavaScript in the VSCode window (like DevTools console) |
vscode_query_selector | Direct document.querySelector() / querySelectorAll() wrapper |
vscode_get_element_by_id | Get element by ID (document.getElementById wrapper) |
vscode_get_elements_by_class | Get elements by class name (document.getElementsByClassName wrapper) |
vscode_get_elements_by_tag | Get elements by tag name (document.getElementsByTagName wrapper) |
Testing Tools
| Tool | Description |
|---|---|
vscode_get_editor_content | Get the current editor's text content |
vscode_verify_element | Verify UI element presence and state |
vscode_assert_text | Assert text content in editor or elements |
vscode_check_file_open | Check if a specific file is open |
Keyboard & Input Tools
| Tool | Description |
|---|---|
vscode_press_keys | Press keyboard keys or key combinations (Ctrl+S, Ctrl+Shift+P, Enter, Escape, etc.) |
vscode_focus_element | Focus a UI element by CSS selector |
vscode_scroll | Scroll an element in a direction or to top/bottom |
vscode_drag_drop | Drag and drop between elements |
vscode_hover | Hover over an element for a duration |
Wait & Sync Tools
| Tool | Description |
|---|---|
vscode_wait_for_element | Wait for an element to appear or disappear |
vscode_wait_for_text | Wait for text to appear or disappear in an element |
vscode_wait_for_idle | Wait for VSCode to become idle (no pending operations) |
Notification & Dialog Tools
| Tool | Description |
|---|---|
vscode_get_notifications | Get all visible notifications with type, message, and actions |
vscode_dismiss_notification | Dismiss a notification by index or message text |
vscode_handle_dialog | Handle modal dialogs (InputBox, QuickPick, confirmations) |
vscode_get_quick_pick_items | Get items from the QuickPick/Command Palette |
vscode_select_quick_pick_item | Select a QuickPick item by text or index |
Extension Testing Tools
| Tool | Description |
|---|---|
vscode_trigger_hover | Trigger hover on an element and get tooltip content |
vscode_open_context_menu | Open context menu (right-click) on an element |
vscode_get_menu_items | Get items from visible menus |
vscode_click_menu_item | Click a menu item by text |
vscode_get_tooltip | Get currently visible tooltip content |
vscode_trigger_completion | Trigger IntelliSense/code completion (Ctrl+Space) |
vscode_get_completion_items | Get IntelliSense completion items |
vscode_select_completion_item | Select and accept a completion item |
vscode_get_problems_panel | Get problems from Problems panel with severity and location |
vscode_go_to_definition | Trigger Go to Definition (F12) |
vscode_trigger_signature_help | Trigger signature help (Ctrl+Shift+Space) |
Debug & Performance Tools
| Tool | Description |
|---|---|
vscode_get_console_logs | Get captured console logs (log, info, warn, error, debug) |
vscode_clear_console | Clear captured console logs |
vscode_get_output_channels | List available output channels |
vscode_get_output_channel_content | Read content from an output channel |
vscode_get_performance_metrics | Get performance metrics (memory, timing, DOM stats) |
vscode_get_extension_logs | Get extension-related logs, optionally filtered by extension ID |
vscode_get_devtools_info | Get DevTools-style window/document/navigator info |
Utility Tools
| Tool | Description |
|---|---|
vscode_initialize | Pre-initialize the VSCode driver |
vscode_get_status | Get the current driver status |
📖 Usage Examples
Execute a Command
// Save the current file
await vscode_execute_command({ commandId: "workbench.action.files.save" });
// Format the document
await vscode_execute_command({ commandId: "editor.action.formatDocument" });
// Open settings
await vscode_execute_command({ commandId: "workbench.action.openSettings" });
Click UI Elements
// Click by CSS selector
await vscode_click_element({
selector: ".explorer-viewlet",
selectorType: "css"
});
// Click by accessibility label
await vscode_click_element({
selector: "Explorer",
selectorType: "accessibility"
});
// Double-click a file
await vscode_click_element({
selector: ".file-item",
selectorType: "css",
doubleClick: true
});
// Right-click for context menu
await vscode_click_element({
selector: ".file-item",
selectorType: "css",
rightClick: true
});
Type Text
// Type into the focused element
await vscode_type_text({ text: "Hello, World!" });
// Type into a specific input and press Enter
await vscode_type_text({
text: "search term",
selector: "input.search-input",
pressEnter: true
});
// Clear and type with a delay (for autocomplete)
await vscode_type_text({
text: "import React from 'react'",
clear: true,
delay: 50
});
Open Files
// Open a file
await vscode_open_file({ filePath: "/path/to/file.ts" });
// Open a file at a specific line
await vscode_open_file({
filePath: "src/index.ts",
line: 42
});
// Open a file at a specific line and column
await vscode_open_file({
filePath: "src/utils.ts",
line: 10,
column: 5
});
Take Screenshots
// Take a screenshot with default name
await vscode_take_screenshot({});
// Take a screenshot with custom filename
await vscode_take_screenshot({
filename: "test-result-screenshot"
});
Get Diagnostics
// Get all diagnostics
await vscode_get_diagnostics({});
// Get only errors
await vscode_get_diagnostics({ severity: "error" });
// Get warnings
await vscode_get_diagnostics({ severity: "warning" });
Inspect the DOM (for AI Agents)
// Get the full page DOM as a readable tree
await vscode_get_dom({});
// Get DOM of a specific element as JSON
await vscode_get_dom({
selector: ".sidebar",
format: "json",
depth: 5
});
// Get raw HTML of an element
await vscode_get_dom({
selector: ".editor-container",
format: "html"
});
// Get the sidebar structure
await vscode_get_ui_structure({ region: "sidebar" });
// Get the editor area structure with more depth
await vscode_get_ui_structure({
region: "editor",
depth: 8
});
// Find all buttons on the page
await vscode_query_elements({ selector: "button" });
// Find elements with a specific role
await vscode_query_elements({
selector: "[role='tab']",
limit: 10
});
// Get the accessibility tree for semantic understanding
await vscode_get_accessibility_tree({});
// Get accessibility tree of a specific region
await vscode_get_accessibility_tree({
selector: ".sidebar",
depth: 6
});
Incremental DOM Exploration (for Large DOMs)
// Step 1: Get top-level children of body
await vscode_get_element_children({ selector: "body" });
// Step 2: Drill into a specific child
await vscode_get_element_children({
selector: ".workbench-container",
depth: 2
});
// Get parent chain to understand context
await vscode_get_element_parents({
selector: ".my-button",
levels: 5
});
// Get siblings (useful for tabs, list items)
await vscode_get_element_siblings({
selector: ".tab:nth-child(2)",
direction: "all"
});
// Find all interactive elements in a region
await vscode_find_interactive_elements({
selector: ".sidebar",
types: ["button", "input", "link"]
});
// Search for elements by text/label
await vscode_search_dom({
query: "Explorer",
searchIn: ["text", "aria-label", "title"]
});
// For very large DOMs: dump to file and read incrementally
await vscode_dump_dom_to_file({
filePath: "/tmp/vscode-dom.json",
format: "json",
depth: 15
});
// Then use file reading tools to explore sections
Execute JavaScript (DevTools Console Style)
// Get the document title
await vscode_execute_script({
script: "return document.title"
});
// Get Monaco editor models (VSCode internals)
await vscode_execute_script({
script: "return window.monaco?.editor?.getModels()?.map(m => m.uri.toString())"
});
// Click an element programmatically
await vscode_execute_script({
script: "document.querySelector('.my-button')?.click(); return 'clicked'",
returnType: "string"
});
// Run complex DOM manipulation
await vscode_execute_script({
script: `
const editors = document.querySelectorAll('.editor-instance');
return Array.from(editors).map(e => ({
id: e.id,
visible: e.offsetWidth > 0
}));
`
});
// Access VSCode's internal APIs (if available)
await vscode_execute_script({
script: "return typeof acquireVsCodeApi !== 'undefined'"
});
Simple DOM Queries (querySelector style)
// Find a single element
await vscode_query_selector({ selector: ".my-button" });
// Find all matching elements
await vscode_query_selector({ selector: "button", all: true });
// Extract specific properties
await vscode_query_selector({
selector: "input",
all: true,
properties: ["value", "placeholder", "type", "name"]
});
// Get element by ID
await vscode_get_element_by_id({ id: "workbench.parts.editor" });
// Get all elements with a class
await vscode_get_elements_by_class({
className: "editor-container",
limit: 10
});
// Get all buttons
await vscode_get_elements_by_tag({
tagName: "button",
properties: ["textContent", "aria-label", "disabled"]
});
// Get all inputs with their values
await vscode_get_elements_by_tag({
tagName: "input",
properties: ["type", "value", "placeholder", "name"]
});
Keyboard & Input
// Press keyboard shortcuts
await vscode_press_keys({ keys: "ctrl+s" }); // Save file
await vscode_press_keys({ keys: "ctrl+shift+p" }); // Command Palette
await vscode_press_keys({ keys: "ctrl+/" }); // Toggle comment
// Press keys multiple times
await vscode_press_keys({ keys: "ArrowDown", count: 5 });
// Focus on a specific element first
await vscode_press_keys({
keys: "Enter",
selector: ".my-button"
});
// Scroll within an element
await vscode_scroll({ direction: "down", amount: 500 });
await vscode_scroll({ selector: ".sidebar", direction: "bottom" });
// Drag and drop
await vscode_drag_drop({
sourceSelector: ".file-item:nth-child(2)",
targetSelector: ".folder-item"
});
// Hover over element
await vscode_hover({
selector: ".status-item",
duration: 1000
});
Waiting & Synchronization
// Wait for an element to appear
await vscode_wait_for_element({
selector: ".notification",
timeout: 5000
});
// Wait for element to disappear
await vscode_wait_for_element({
selector: ".loading-spinner",
present: false,
timeout: 10000
});
// Wait for specific text
await vscode_wait_for_text({
text: "Build succeeded",
selector: ".terminal",
timeout: 30000
});
// Wait for VSCode to be idle
await vscode_wait_for_idle({ timeout: 5000 });
Notifications & Dialogs
// Get all notifications
await vscode_get_notifications({});
// Dismiss a notification by message
await vscode_dismiss_notification({
messageContains: "Extension installed"
});
// Handle input dialog
await vscode_handle_dialog({
text: "my-new-file.ts",
action: "accept"
});
// Get QuickPick items (Command Palette)
await vscode_press_keys({ keys: "ctrl+shift+p" });
await vscode_get_quick_pick_items({});
// Select a QuickPick item
await vscode_select_quick_pick_item({
text: "Format Document"
});
IntelliSense & Code Navigation
// Trigger completion
await vscode_trigger_completion({});
// Get completion items
await vscode_get_completion_items({ limit: 20 });
// Select a completion item
await vscode_select_completion_item({
itemLabel: "console.log"
});
// Go to definition
await vscode_go_to_definition({});
// Trigger signature help
await vscode_trigger_signature_help({});
// Trigger hover and get tooltip
await vscode_trigger_hover({
selector: ".view-line span"
});
// Open context menu
await vscode_open_context_menu({
selector: ".file-item"
});
// Get and click menu items
await vscode_get_menu_items({});
await vscode_click_menu_item({ itemText: "Rename" });
Debug & Performance
// Get console logs
await vscode_get_console_logs({ level: "error" });
// Get all recent logs
await vscode_get_console_logs({ limit: 50 });
// Clear console logs
await vscode_clear_console({});
// Get output channels
await vscode_get_output_channels({});
// Read from an output channel
await vscode_get_output_channel_content({
channelName: "Extension Host"
});
// Get extension logs
await vscode_get_extension_logs({
extensionId: "my.extension"
});
// Get performance metrics
await vscode_get_performance_metrics({});
// Get DevTools info
await vscode_get_devtools_info({});
Verify UI State
// Check if an element exists and is visible
await vscode_verify_element({
selector: ".explorer-viewlet",
selectorType: "css",
shouldBeVisible: true
});
// Check if element contains specific text
await vscode_verify_element({
selector: ".statusbar",
selectorType: "css",
containsText: "TypeScript"
});
Get Editor Content
// Get the content of the active editor
const result = await vscode_get_editor_content({});
// Returns: { content: "...", editor: { fileName: "...", lineCount: ... } }
🔧 Common Command IDs
Here are some frequently used VSCode command IDs:
File Operations
workbench.action.files.save- Save fileworkbench.action.files.saveAll- Save all filesworkbench.action.files.newUntitledFile- New fileworkbench.action.closeActiveEditor- Close editor
Navigation
workbench.action.quickOpen- Quick Open (Ctrl+P)workbench.action.gotoLine- Go to Lineeditor.action.revealDefinition- Go to Definition
View
workbench.action.toggleSidebarVisibility- Toggle Sidebarworkbench.action.togglePanel- Toggle Panelworkbench.action.terminal.toggleTerminal- Toggle Terminal
Editor
editor.action.formatDocument- Format Documenteditor.action.commentLine- Toggle Line Comment
Git
git.commit- Git Commitgit.push- Git Pushgit.pull- Git Pull
🧪 Testing the MCP Server
Manual Testing
-
Build the project:
npm run build npm run validate -
Test with MCP Inspector (recommended):
npx @modelcontextprotocol/inspector node dist/index.jsThis opens a web UI where you can call each tool interactively.
-
Test with Claude Desktop:
- Add the server to your Claude Desktop config (see Configuration section)
- Restart Claude Desktop
- Ask Claude to use the vscode_automation tools
-
Test basic functionality:
# Start the server manually to check for startup errors node dist/index.jsThe server communicates via stdio, so you won't see output unless there are errors.
What Gets Tested
vscode_get_status- Always works, returns server statevscode_initialize- Launches VSCode with WebDriver (requires display)- All other tools - Require
vscode_initializeto be called first
Notes on Testing
- The server uses vscode-extension-tester which launches a real VSCode instance
- First run may take time to download ChromeDriver
- VSCode must be installed on the system
- Requires a display (or virtual display on Linux)
🐛 Troubleshooting
VSCode Not Found
Make sure VSCode is installed and accessible from the command line:
code --version
ChromeDriver Issues
The server uses ChromeDriver to automate VSCode. If you encounter issues:
- Make sure Chrome/Chromium is installed
- The correct ChromeDriver version will be downloaded automatically
- Check that no other automation tools are conflicting
Timeout Errors
If operations are timing out:
- Increase the timeout in the tool options
- Make sure VSCode has finished loading
- Call
vscode_initializebefore other operations
Element Not Found
If selectors aren't finding elements:
- Use
vscode_take_screenshotto see the current state - Try different selector types (css, xpath, accessibility, text)
- Check if the element is in a webview (requires different handling)
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
- Model Context Protocol - The protocol that makes this possible
- MCP TypeScript SDK - The SDK used to build this server
- vscode-extension-tester - The automation library powering this server
- Anthropic - For creating Claude and the MCP specification
Built with ❤️ by Sukarth