VS Code MCP Server

A Visual Studio Code extension (available on the Marketplace) that allows Claude and other MCP clients to code directly in VS Code! Inspired by Serena, but using VS Code's built-in capabilities. This is currently far simpler than Serena, but it works! Note that this extension uses the streamable HTTP API, not the SSE API.

This 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.

PRs are welcome!

Demo Video

demo_video.mp4

Installation

1. Install the extension from the Marketplace or clone this repository and run npm install and npm run compile to build it.

Claude Desktop Configuration

Claude 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:

{
  "mcpServers": {
    "vscode-mcp-server": {
        "command": "npx",
        "args": ["mcp-remote@next", "http://localhost:3000/mcp"]
    }

  }
}

I 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:

You are working on an existing codebase, which you can access using your tools. These code tools interact with a VS Code workspace.

Before running code tools that will make any modification to code, always present a comprehensive and detailed plan to the user, including your confidence level (out of 10). When planning, use your tools to explore the codebase so that you understand the context of the project. If you are not confident in your plan because you require more information, use your tools, such as web search, to look for this information or ask the user.

IMPORTANT: Only run code tools that will modify code after presenting such a plan to the user, and receiving explicit approval. Approval must be given each time; prior approval for a change does not imply that subsequent changes are approved.

This extension serves as a Model Context Protocol (MCP) server, exposing VS Code's filesystem and editing capabilities to MCP clients.

Features

The VS Code MCP Server extension implements an MCP-compliant server that allows AI models and other MCP clients to:

• Browse the workspace — list directories and read file contents (with smart truncation, line ranges, encoding support)
• Edit code with apply_diff — multi-section edits, fuzzy matching for whitespace/drift, atomic or partial-success modes, VS Code diff viewer with status-bar Apply/Reject UI
• Search and inspect symbols — workspace symbol search and per-symbol definition/hover lookup
• Get diagnostics — pull errors and warnings from VS Code's language servers
• Run shell commands — interactive, background, or one-shot, in named shells, with safety warnings on destructive commands and per-shell timeouts
• Manage shell sessions — list active shells, send input to interactive prompts, capture full terminal output, close shells explicitly
• Count tokens — count Anthropic API tokens for arbitrary text or one-or-more file ranges (uses Anthropic's official Token Counting API)
• Toggle the server and approval modes from a status bar menu

This extension enables AI assistants and other tools to interact with your VS Code workspace through the standardized MCP protocol.

How It Works

The extension creates an MCP server that:

1. Runs locally on a configurable port (when enabled)
2. Handles MCP protocol requests via HTTP
3. Exposes VS Code's functionality as MCP tools
4. Provides a status bar indicator showing server status, which can be clicked to toggle the server on/off

Supported MCP Tools

Line numbering note: All tools that accept or return line numbers use 1-based indexing, matching VS Code's editor display.

File Tools

• list_files_code — Lists files and directories in your workspace.

  • Parameters:
    • path: The path to list files from
    • recursive (optional): Whether to list files recursively. Avoid recursive on the workspace root for large projects.

• read_file_code — Reads file contents with smart truncation.

  • Parameters:
    • path: The path to the file to read
    • encoding (optional): File encoding (default: utf-8)
    • maxCharacters (optional): Maximum character count (default: 200,000)
    • startLine (optional, 1-based, inclusive): Read from this line. Default: from start.
    • endLine (optional, 1-based, inclusive): Read to this line. Default: to end (-1).
  • Behavior: When the response would exceed ~99,000 characters the tool truncates at the last complete line and returns metadata (outputToLine, linesLeftToEndLine, linesLeftToEOF) plus a continuation hint specifying exactly which startLine/endLine to use for the next call.

• count_tokens — Counts Anthropic API tokens for arbitrary text or file content. Useful for cost estimation and context-window planning.

  • Parameters (mutually exclusive modes):
    • text: Direct text to count, or
    • filepath + optional startLine/endLine (1-based) for a single range, or
    • filepath + lineRanges: array of { startLine, endLine?, description? } for multiple discontinuous ranges in a single call
    • model (optional): Defaults to claude-sonnet-4-5-20250929
  • Requires the ANTHROPIC_API_KEY environment variable. Files >16 MB warn; >512 MB are rejected.

Edit Tools

• apply_diff — Apply one or more search/replace edits to a file with fuzzy matching. The flagship edit tool.
  • Parameters:
    • filePath: The file to modify (auto-creates the file if it doesn't exist)
    • diffs: Array of { startLine, endLine, search, replace, description? } (line numbers 1-based; endLine: -1 means end-of-file)
    • description (optional): Overall change description
    • partialSuccess (optional, default false): If true, applies sections that match and reports the rest; if false, all-or-nothing
  • Features:
    • Multiple diff sections in one call, applied atomically (or with partialSuccess)
    • Fuzzy matching tolerates whitespace and minor content drift (exact → normalized → contextual → similarity strategies)
    • Full-file replacement: startLine: 1, endLine: -1, empty search
    • Approval UI: opens VS Code's diff viewer with status-bar Apply / Reject buttons (auto-rejects after 30 s); auto-approval mode is available but off by default

Shell Tools

Command Execution

• execute_shell_command_code — Run a command in a VS Code integrated terminal with shell-integration-aware output capture.
  • Parameters:
    • command: The shell command to execute
    • cwd (optional, default .): Working directory
    • shellId (optional): Reuse a specific shell (e.g. shell-1); otherwise a default/new shell is used
    • interactive (optional): Use a 45 s timeout (vs the 15 s default) for commands that prompt
    • background (optional): No timeout; returns immediately while output streams to the shell's output file
    • silenceOutput (optional): Suppress inline output in the response; full output is still saved to the output file
  • Behavior: Output >100 K characters is truncated inline and the full output is written to <workspace>/.vscode-mcp-output/<shellId>-output.txt. Detects potentially destructive commands (rm -rf, format, etc.) and surfaces warnings in the response.

Shell Management

• list_active_shells — Lists all active shell sessions with status (idle / busy / waiting-for-input / crashed), CWD, current command, age, and remaining timeout. Shells with <5 s left are flagged with ⚠️.

• send_input_to_shell — Send text into a shell that's waiting for input, optionally capturing the resulting terminal output.

  • Parameters:
    • shellId: Target shell (e.g. shell-1)
    • input: Text to send
    • includeNewline (optional, default true): Append a newline
    • captureOutput (optional, default true): Use VS Code's terminal selection commands to copy the full terminal buffer into the response (last 20 lines inline; full text persisted to the shell's output file). Bypasses shell-integration limits and works with arbitrary interactive CLIs (scaffolders, wizards, etc.).
  • Resets the shell's timeout to 45 s on input.

• close_shell — Close and clean up a specific shell session.

  • Parameters: shellId
  • Disposes the terminal and clears its timeout. The output file at .vscode-mcp-output/<shellId>-output.txt is preserved for post-mortem inspection.

Workspace Context

• get_workspace_context — Returns CWD, workspace folder paths, basic project info (from package.json if present), and a summary of active shells. No parameters.

Diagnostics Tools

• get_diagnostics_code — Returns errors/warnings from VS Code's language servers.
  • Parameters:
    • path (optional): Limit to a single file; otherwise scans the workspace
    • severities (optional, default [0,1]): 0=Error, 1=Warning, 2=Info, 3=Hint
    • format (optional, default text): text or json
    • includeSource (optional, default true): Include the linter/source identifier
  • Useful for verifying fixes and pre-commit checks. Output line numbers are 1-based.

Symbol Tools

• search_symbols_code — Fuzzy workspace symbol search.

  • Parameters: query, maxResults (optional, default 10)
  • Returns location, kind, and container info per match.

• get_symbol_definition_code — Type/hover info for a symbol at a specific line.

  • Parameters:
    • path: File containing the symbol
    • line: 1-based line number
    • symbol: Symbol name to resolve at that line
  • Returns type info, documentation, and surrounding code context.

Shell Timeout & Output Behavior

The shell tools implement an intelligent timeout system to prevent hanging while supporting interactive workflows:

1. Timeout durations:

   • Regular commands: 15 seconds
   • Interactive commands: 45 seconds
   • Background processes: no timeout

2. Timeout reset:

   • Executing a new command in a shell clears any existing timeout
   • Sending input via send_input_to_shell resets the timeout to 45 s
   • This keeps long interactive sessions from timing out prematurely

3. Timeout visibility:

   • list_active_shells shows the remaining timeout for each shell
   • Shells with <5 s remaining are flagged with ⚠️

4. Shell lifecycle:

   • Maximum 8 concurrent shells
   • Idle shells auto-cleanup after 10 minutes of inactivity
   • Crashed shells can be reused with the same ID

5. Output file persistence (<workspace>/.vscode-mcp-output/):

   • Every shell writes its full output to <shellId>-output.txt
   • Files are preserved when shells close so you can inspect runs that timed out or were closed accidentally
   • Each new run in a shell overwrites that shell's file (no append)
   • Manual cleanup: delete files from .vscode-mcp-output/ when no longer needed

Caveats/TODO

Currently, 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.

Extension Settings

This extension contributes the following settings:

• vscode-mcp-server.port (number, default 3000): Port for the MCP HTTP server (range 1024–65535).
• vscode-mcp-server.defaultEnabled (boolean, default false): Auto-start the server when VS Code finishes startup.

Status Bar & Approval Modes

A single status bar menu (right side) shows server state and exposes:

• Toggle MCP Server — start/stop the HTTP server.
• Toggle Apply Diff Auto-Approval — when enabled, apply_diff calls bypass the Apply/Reject prompt and apply automatically. Off by default; intended for trusted automation. A confirmation modal warns before enabling.
• Toggle Shell Auto-Approval (DANGEROUS) — when enabled, shell commands run without confirmation. Off by default; never enabled in test mode. A strong warning modal is shown before enabling.

When apply_diff runs without auto-approval, VS Code's diff viewer opens and an Apply / Reject pair appears in the status bar. No response within 30 s auto-rejects the diff.

Using with MCP Clients

To connect MCP clients to this server, configure them to use:

http://localhost:3000/mcp

Remember that you need to enable the server first by clicking on the status bar item!

Documentation

The docs/ directory contains supplementary guides:

• docs/vscode-setup.md — Full VSCode extension and settings export. Includes a one-shot CLI install script, a .vscode/extensions.json recommendations block, the complete workspace settings.json, and per-extension descriptions grouped by category.

Contributing

Contributions are welcome! Feel free to submit issues or pull requests.

License

MIT