Skip to main content
Glama
kimkun07-k
by kimkun07-k

vs-mcp-server

Visual Studio 2022를 Claude Code(MCP)에서 제어하는 서버. COM/DTE 자동화를 통해 파일 열기, 빌드, 디버거 제어, 브레이크포인트 관리 등을 MCP 도구로 제공한다.

Windows 전용. COM/DTE는 Windows에서만 동작한다.


빠른 시작

1. 패키지 설치

pip install vs-mcp-server

2. MCP 서버 등록 — Claude Code CLI

# uvx 방식 (권장, 가상환경 자동 관리)
claude mcp add --scope project vs -- uvx vs-mcp-server

# 또는 pip install 후 — 직접 실행 방식
claude mcp add --scope project vs -- vs-mcp-server

등록 방법(전역, Desktop, 환경변수 등)은 설치 및 MCP 서버 등록 섹션을 참고한다.

3. Visual Studio 2022 실행

VS가 이미 실행 중이면 건너뛴다. 실행하지 않았다면 vs_launch 도구로 자동 실행할 수 있다.

4. Claude Code에서 VS 연결

vs_connect(session_id="s1", solution_path="C:/MyProject/MyProject.sln")

5. 도구 사용 시작

vs_file_open(session_id="s1", path="C:/MyProject/src/main.cpp")
vs_debug_evaluate(session_id="s1", expression="myVar.Value")

Related MCP server: AutoCAD MCP Server

아키텍처

Claude Code (MCP Client)
        │  stdio
        ▼
  server.py  ── 22개 도구 등록, 라우팅
        │
  session_manager.py  ── 세션 ↔ VS 인스턴스 바인딩
        │
  com_bridge.STAThread  ── VS 인스턴스 1개당 STA 전용 스레드
        │  immediate / long_running 채널
        ▼
  EnvDTE COM (devenv.exe)  ── out-of-process COM 서버
        │  ROT (Running Object Table)
        ▼
  Visual Studio 2022

핵심 설계 원칙:

  • STA 전용 스레드: EnvDTE COM은 STA(Single-Threaded Apartment)에서만 안정적으로 동작. VS 인스턴스 1개당 STAThread 1개를 할당.

  • 듀얼 채널: immediate(에디터 조작 등 빠른 명령) / long_running(빌드 등 오래 걸리는 명령) 채널을 분리하여 빌드 중에도 즉시 채널 처리 가능.

  • ROT 탐색: Running Object Table에서 VisualStudio.DTE.17.0 모니커를 검색하여 실행 중인 VS 인스턴스에 연결.

  • 크래시 로깅: vs_debug_evaluate 결과, COM 오류, 타임아웃을 logs/vs_mcp_crash.jsonl에 자동 기록.


사전 요구사항

항목

버전 / 조건

OS

Windows 10 / 11 (COM/DTE는 Windows 전용)

Python

3.11 이상

Visual Studio

2022 Community / Professional / Enterprise

패키지

pywin32, mcp

# Python 버전 확인
python --version

설치 및 MCP 서버 등록

Claude Code CLI에 등록

Claude Code CLI는 .mcp.json 파일로 MCP 서버를 관리한다.

방법 1 — uvx 방식 (권장)

별도 설치 없이 uvx가 자동으로 가상환경을 만들어 실행한다.

# 프로젝트별 등록
claude mcp add --scope project vs -- uvx vs-mcp-server

# 전역 등록
claude mcp add --scope user vs -- uvx vs-mcp-server

또는 .mcp.json 직접 작성:

{
  "mcpServers": {
    "vs": {
      "command": "uvx",
      "args": ["vs-mcp-server"]
    }
  }
}

방법 2 — pip install 후 직접 실행

# 설치 (git clone 불필요)
pip install vs-mcp-server
# 또는 GitHub에서 직접 설치
pip install git+https://github.com/panninghour/vs-mcp-server

# 등록
claude mcp add --scope project vs -- vs-mcp-server

또는 ~/.claude.json(%USERPROFILE%\.claude.json)에 직접 작성:

{
  "mcpServers": {
    "vs": {
      "command": "vs-mcp-server"
    }
  }
}

방법 3 — 개발자용 (로컬 편집 가능 설치)

소스를 수정하면서 사용하려면:

git clone https://github.com/panninghour/vs-mcp-server
cd vs-mcp-server
pip install -e .
claude mcp add --scope project vs -- vs-mcp-server

등록 확인

# 등록된 MCP 서버 목록 확인
claude mcp list

Claude Code 세션 안에서 서버 상태와 도구 목록을 확인하려면:

/mcp

vs 서버가 연결됨으로 표시되고, vs_connect, vs_debug_evaluate 등 22개 도구가 활성화되어야 한다.


Claude Desktop에 등록

claude_desktop_config.json을 열어 mcpServers에 추가한다.

파일 위치 (Windows):

%APPDATA%\Claude\claude_desktop_config.json

설정 예시 (uvx 방식):

{
  "mcpServers": {
    "vs": {
      "command": "uvx",
      "args": ["vs-mcp-server"],
      "env": {
        "VS_DEVENV_PATH": "C:/Program Files/Microsoft Visual Studio/2022/Professional/Common7/IDE/devenv.exe"
      }
    }
  }
}

Claude Desktop 재시작 후 반영된다.


환경변수 설정

환경변수

기본값

설명

VS_DEVENV_PATH

Community 설치 경로

devenv.exe 전체 경로. Professional/Enterprise 사용 시 재정의 필요.

VS_MCP_LOG_DIR

<server.py 위치>/logs/

크래시 로그 저장 디렉토리

VS_MCP_LOG_LEVEL

INFO

로그 레벨 (DEBUG / INFO / WARNING)

VS 설치 경로 예시:

# Community (기본값)
C:\Program Files\Microsoft Visual Studio\2022\Community\Common7\IDE\devenv.exe

# Professional
C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\devenv.exe

# Enterprise
C:\Program Files\Microsoft Visual Studio\2022\Enterprise\Common7\IDE\devenv.exe

환경변수를 영구 설정하려면:

[System.Environment]::SetEnvironmentVariable(
    "VS_DEVENV_PATH",
    "C:\Program Files\Microsoft Visual Studio\2022\Professional\Common7\IDE\devenv.exe",
    "User"
)

또는 .mcp.jsonenv 블록으로 서버별 설정:

"env": {
  "VS_DEVENV_PATH": "C:/Program Files/Microsoft Visual Studio/2022/Professional/Common7/IDE/devenv.exe"
}

도구 목록

인스턴스 관리

도구

설명

vs_list_instances

ROT에서 실행 중인 VS 인스턴스 목록(PID, 솔루션 경로) 반환

vs_connect

PID 또는 솔루션 경로로 VS 인스턴스에 연결, 세션 바인딩

vs_launch

devenv.exe 실행 후 ROT 폴링으로 자동 연결

vs_close

VS 인스턴스 종료 (save_all 옵션)

에디터 — Claude → 유저

도구

설명

vs_file_open

파일을 VS 에디터에 열어 유저에게 보여줌

vs_file_goto

특정 파일의 라인/컬럼으로 커서 이동

vs_file_highlight

라인 범위를 선택 상태로 강조 (add_bookmark 옵션)

vs_file_list_open

열린 파일 목록과 저장 상태 반환

에디터 — 유저 → Claude

도구

설명

vs_file_active

유저가 현재 포커스 중인 파일 경로와 커서 위치(line/column) 반환

vs_file_selection

유저가 드래그로 선택한 텍스트와 범위 반환

빌드

도구

설명

vs_build_solution

솔루션 전체 비동기 빌드, 결과 반환

vs_build_project

특정 프로젝트만 빌드

vs_build_status

마지막 빌드 결과 및 현재 빌드 상태 조회

vs_error_list

Build Output에서 에러/경고를 파싱하여 파일 경로·라인 번호와 함께 반환

디버깅

도구

설명

vs_debug_start

디버깅 시작 (Debugger.Go), wait_for_break 옵션

vs_debug_stop

디버깅 종료, Design 모드로 복귀

vs_debug_breakpoint

브레이크포인트 추가(add)/제거(remove)/목록 조회(list)

vs_debug_step

스텝 실행 (into / over / out)

vs_debug_locals

Break 모드에서 현재 스택 프레임의 로컬 변수 반환

vs_debug_evaluate

Break 모드에서 표현식 평가 및 결과 반환

vs_debug_callstack

현재 스레드의 콜스택(함수명/파일/라인) 반환

큐 관리

도구

설명

vs_queue_status

현재 실행 중인 명령과 대기 큐 목록 반환

vs_queue_cancel

대기 큐의 명령을 command_id로 취소

vs_queue_history

최근 N건의 명령 이력(완료/실패/취소) 반환

DTE 범용

도구

설명

vs_command

dte.ExecuteCommand()로 VS 명령 실행. 6000+ 명령에 접근 가능 (Edit.FormatDocument, File.SaveAll 등)


사용 예시

# 1. VS 인스턴스 목록 확인
vs_list_instances()
# → [{"pid": 12345, "solution": "C:/MyProject/MyProject.sln"}]

# 2. 세션 연결
vs_connect(session_id="s1", solution_path="C:/MyProject/MyProject.sln")

# 3. 파일 열기 + 특정 라인으로 이동
vs_file_open(session_id="s1", path="C:/MyProject/src/main.cpp")
vs_file_goto(session_id="s1", path="C:/MyProject/src/main.cpp", line=42)

# 4. 유저가 선택한 코드 읽기
vs_file_selection(session_id="s1")
# → {"text": "int x = foo();", "start_line": 42, "end_line": 42}

# 5. 빌드
vs_build_solution(session_id="s1", configuration="Debug")
# → {"success": true, "failed_projects": 0}

# 6. 브레이크포인트 추가 후 디버깅 시작
vs_debug_breakpoint(session_id="s1", action="add", file="C:/MyProject/src/main.cpp", line=42)
vs_debug_start(session_id="s1", wait_for_break=False)

# 7. Break 모드 진입 후 변수 검사
vs_debug_locals(session_id="s1")
vs_debug_evaluate(session_id="s1", expression="myObj.Value")
vs_debug_callstack(session_id="s1")

# 8. 스텝 실행
vs_debug_step(session_id="s1", step_type="over")

# 9. 디버깅 종료
vs_debug_stop(session_id="s1")

# 10. DTE 명령 직접 실행
vs_command(session_id="s1", command="Edit.FormatDocument")
vs_command(session_id="s1", command="File.SaveAll")

테스트

단위 테스트 (mock 기반)

python -m pytest tests/ -v --ignore=tests/test_integration_vs.py

통합 테스트 (실제 VS 2022 필요)

VS 2022가 실행 중인 상태에서:

python -m pytest tests/test_integration_vs.py -v -s

VS가 미실행이면 자동으로 실행 후 ROT 등록을 대기한다.

통합 테스트 항목 (IT 그룹 18개, pytest 함수 28개):

그룹

ID

검증 내용

ROT 감지

IT-001

VS 인스턴스 감지, PID 검증, get_vs_pid() 정확성, 스테일 항목 필터링

DTE 속성

IT-002

MainWindow, Solution, Version COM 속성 접근

파일 열기

IT-003

vs_file_openActiveDocument 변경 확인

파일 목록/활성

IT-004

vs_file_list_open, vs_file_active round-trip

빌드 상태

IT-005

vs_build_status 반환값 검증

브레이크포인트

IT-006

add / list / remove CRUD

디버거 모드

IT-007

Design 모드 확인, vs_debug_stop

STAThread 큐

IT-008

실제 큐 메커니즘 및 이력 기록 확인

커서 이동

IT-009

vs_file_gotovs_file_active round-trip

하이라이트

IT-010

vs_file_highlight 범위 선택

선택 텍스트

IT-011

vs_file_selection 반환값

디버깅 세션

IT-012

새 VS 인스턴스에 DebugTarget.sln 로드, Debug 빌드, BP 설정 후 Break 모드 진입 확인

디버깅 세션

IT-013

Break 모드에서 vs_debug_localsx=42, y=50, msg 변수 확인

디버깅 세션

IT-014

vs_debug_evaluate("x + y") == "92", msg"hello from debugger" 포함

디버깅 세션

IT-015

vs_debug_callstackdepth >= 1, .NET 8 CurrentStackFrame 폴백 동작

디버깅 세션

IT-016

vs_debug_step("over")mode == "break", line > BP_LINE, ActiveDocument 폴백 동작

디버깅 세션

IT-017

vs_debug_stop()status == "stopped", mode == "design"

DTE 범용

IT-018

vs_command("Edit.LineEnd") 실행 후 status == "executed", 잘못된 명령 시 COM 예외 전파

Error List

IT-019

ErrorTarget.sln 빌드 후 vs_error_list → CS0103 에러, CS1030 경고 파싱 확인


설정

환경변수로 조정 가능. 개발자용 설치(pip install -e .)의 경우 vs_mcp_server/config.py에서 직접 수정할 수도 있다.

설정

기본값

설명

timeouts["build"]

600초

빌드 최대 대기 시간

timeouts["launch"]

120초

VS 실행 후 ROT 등록 대기

timeouts["debug_evaluate"]

10초

표현식 평가 타임아웃

VS_DEVENV_PATH

Community 경로

devenv.exe 경로 (환경변수로 재정의 가능)

QUEUE_HISTORY_MAX

100

명령 이력 최대 보존 건수


알려진 제약사항

  • Windows 전용: COM/DTE는 Windows에서만 동작한다.

  • VS 2022 전용: VisualStudio.DTE.17.0 모니커만 지원한다.

  • Python 3.11+: 하위 버전에서는 동작을 보장하지 않는다.

  • STAThread cross-apartment: STAThread 내에서 DTE를 사용할 때는 ROT에서 직접 DTE를 재획득해야 한다. 메인 스레드의 DTE 포인터를 STAThread에 전달하면 RPC_E_WRONG_THREAD 발생.

  • Break 모드 전용 기능: vs_debug_step, vs_debug_locals, vs_debug_evaluate, vs_debug_callstack은 디버거가 Break 모드일 때만 동작한다.

  • .NET 8 관리 코드 제한: CurrentThread.StackFrames COM 열거가 빈 컬렉션을 반환하는 경우가 있음. vs_debug_callstackCurrentStackFrame 폴백으로 처리하고, vs_debug_stepActiveDocument.Selection 폴백으로 처리한다.

  • DTE2 접근 불가 (Python): 아래 DTE2 제약사항 참고.


DTE2 제약사항 (Python)

문제

Python pywin32는 EnvDTE80.DTE2 전용 속성(ToolWindows 등)에 접근할 수 없다. VisualStudio.DTE.17.0 ProgID로 ROT에서 획득한 COM 객체의 기본 IDispatch는 EnvDTE._DTE(v7.0)이며, ToolWindows는 DTE2 IDispatch vtable의 DispId 300에만 존재한다.

접근 방식

DTE2 캐스트

ToolWindows

ErrorList

Python pywin32

부분적(래핑)

FAIL

-

PowerShell 5.1/7

FAIL

FAIL

-

C# .NET 콘솔앱

SUCCESS

SUCCESS

SUCCESS

Late-binding 검증에서도 InvokeMember("ToolWindows")DISP_E_UNKNOWNNAME (0x80020006)을 반환하여, IDispatch 자체에 ToolWindows가 없음이 확인되었다. C#만이 (DTE2)dte 캐스트 시 COM QueryInterface를 통해 DTE2 vtable을 직접 획득한다.

시도한 접근법

  1. Python win32com.client.Dispatch: gen_py 캐시 유무에 관계없이 DTE2 속성 접근 불가

  2. Python win32com.client.dynamic.Dispatch: late-bound 강제 → DISP_E_UNKNOWNNAME (IDispatch에 없음)

  3. Python _oleobj_.GetIDsOfNames("ToolWindows"): 동일하게 DISP_E_UNKNOWNNAME

  4. C# 브릿지 (subprocess): DTE2 캐스트 성공, ToolWindows.ErrorList 접근 가능. 그러나 ErrorList.ErrorItems가 외부 COM 프로세스에서 항상 빈 컬렉션 반환 — Build Output 파싱으로 우회 필요

현재 해결 방법

vs_error_list는 DTE1에서 접근 가능한 OutputWindow의 Build pane 텍스트를 파싱하여 에러/경고를 반환한다:

# DTE1으로 접근 가능 (ToolWindows 불필요)
ow = dte.Windows.Item("{34E76E81-EE4A-11D0-AE2E-00A0C90FFFC3}").Object
pane = ow.OutputWindowPanes.Item("Build")
text = pane.TextDocument.StartPoint.CreateEditPoint().GetText(pane.TextDocument.EndPoint)
# → MSBuild 출력 형식 정규식 파싱

이 방식은 C# 브릿지나 추가 런타임 없이 순수 Python으로 동작한다.


DTE 직접 접근 (Advanced)

MCP 서버를 거치지 않고 외부 Python 스크립트에서 직접 DTE COM 객체에 접근할 수 있다. VS 인스턴스는 Windows ROT(Running Object Table)에 VisualStudio.DTE.17.0 모니커로 등록되어 있다.

단일 VS 인스턴스

import pythoncom
import win32com.client

pythoncom.CoInitialize()
dte = win32com.client.GetActiveObject("VisualStudio.DTE.17.0")

# 예시: 솔루션 경로 출력
print(dte.Solution.FullName)

주의: GetActiveObject는 VS 인스턴스가 여러 개 실행 중일 때 어느 인스턴스를 반환할지 보장하지 않는다. 단일 인스턴스 환경에서만 사용할 것.

복수 VS 인스턴스 — PID로 특정 인스턴스 선택

vs_list_instances 도구로 PID를 확인한 뒤, ROT에서 해당 PID의 인스턴스를 직접 획득한다.

import pythoncom
import win32com.client
from vs_mcp_server.utils.rot import find_vs_instances, get_vs_pid

pythoncom.CoInitialize()

target_pid = 12345  # vs_list_instances 또는 vs_connect 응답의 instance_pid

entries = find_vs_instances()
dte = next(
    e["dte"] for e in entries
    if get_vs_pid(e["dte"]) == target_pid
)

# 이후 dte 객체를 자유롭게 사용
print(dte.Solution.FullName)

참고: find_vs_instances()는 ROT를 순회하여 모든 VisualStudio.DTE.17.0 항목을 반환한다. get_vs_pid(dte)는 DTE의 MainWindow.HWnd에서 PID를 추출한다.

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    F
    maintenance
    MCP server that integrates with VS Code to enable file operations, git diffs, and line highlighting via MCP clients like Claude.
    41
    MIT
  • A
    license
    Not graded
    quality
    D
    maintenance
    Enables programmatic control of AutoCAD through COM automation, allowing natural language commands to create structures, manage layers, and manipulate entities via MCP clients like Claude.
    62
    Apache 2.0
  • A
    license
    Not graded
    quality
    A
    maintenance
    A native Visual Studio 2026 extension implementing Claude Code's IDE integration protocol: agent edits open in VS's diff viewer for accept/reject, and MCP servers expose the live debugger (stepping, data breakpoints, attach), Test Explorer runs, and Roslyn navigation with decompile to the agent.
    87
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI clients to control local Windows development tools by exposing project files, code search, file editing, test execution, Git operations, and resource viewing through a secure MCP interface with permission controls.
    10
    Apache 2.0