튜토리얼

Windows에서 MCP 서버를 설정하는 방법

대부분의 MCP 설정 가이드는 Mac과 JSON 파일을 전제로 합니다. 이 가이드는 Windows용이며, 무료 오픈소스 데스크톱 AI 앱 Conduit을 클라이언트로 씁니다. 무엇을 설치할지, 각 칸에 무엇을 입력할지, 서버가 시작되지 않을 때 오류가 무슨 뜻인지 알려 드립니다.

소개

Model Context Protocol(MCP)을 쓰면 AI 앱이 다른 프로그램의 도구를 쓸 수 있습니다. 파일을 읽고 쓰고, 문서를 검색하고, 데이터베이스에 질의하고, 이슈를 여는 일입니다. 도구 묶음마다 MCP 서버가 하나씩 있습니다. 로컬 서버는 앱이 사용자의 컴퓨터에서 시작하는 프로그램으로, 대개 npx(Node.js)나 uvx(Python)로 시작합니다. 원격 서버는 다른 곳에서 실행되며 URL로 연결합니다.

Windows에서 로컬 서버가 실패하는 이유는 몇 가지로 정해져 있습니다. 런타임이 설치되어 있지 않거나 PATH에 없는 경우, 앱이 셸 스크립트를 프로그램으로 실행하려는 경우, 폴더 경로에 공백이 있는 경우입니다. 이 튜토리얼은 이를 하나씩 피해 갑니다.

Node.js와 uv를 설치하고, 공식 Filesystem 서버를 npx로, Fetch 서버를 uvx로 추가하고, Microsoft 문서용 원격 서버인 Microsoft Learn도 추가합니다. 그다음 채팅에서 이 서버들을 쓰고, 파일을 바꾸는 도구를 승인하고, 시작되지 않는 서버는 어떤 모습이며 어떻게 고치는지 확인합니다. Conduit에서는 MCP 서버를 커넥터라고 부릅니다.

핵심 요약

준비 사항

이 튜토리얼을 따라 하려면 다음이 필요합니다.

1단계 — Node.js와 uv 설치하기

로컬 MCP 서버는 대부분 npx로 시작하는 Node.js 패키지이거나 uvx로 시작하는 Python 패키지입니다. 이 단계에서는 두 런타임을 모두 설치합니다.

PowerShell을 열고 다음을 실행하세요.

winget install OpenJS.NodeJS.LTS
winget install astral-sh.uv

uv가 각 서버에 필요한 Python 버전을 내려받으므로 Python을 따로 설치할 필요가 없습니다. PowerShell을 닫고 새 창을 열어 둘 다 찾을 수 있는지 확인하세요.

npx --version
uvx --version

각각 버전 번호가 출력됩니다. PowerShell이 명령을 인식하지 못한다고 하면, 새 PATH가 적용되도록 Windows에서 로그아웃했다가 다시 로그인한 뒤 다시 시도하세요.

마지막으로 Conduit를 종료하고 다시 여세요. 트레이에서 아직 실행 중이라면 거기서도 종료하세요. 프로그램은 시작될 때의 PATH를 봅니다. 설치하는 동안 열려 있던 Conduit는 아직 npx나 uvx를 찾지 못합니다.

다음으로 첫 서버를 추가합니다.

2단계 — npx로 로컬 서버 추가하기

Filesystem 서버는 어시스턴트에게 파일을 나열하고, 읽고, 검색하고, 쓰는 도구를 주지만, 사용자가 지정한 폴더 안에서만 가능합니다. 이 단계에서는 폴더 하나에 대해 이 서버를 추가합니다.

사이드 레일에서 컨텍스트를 선택하고, 위쪽에서 커넥터를, 그다음 커넥터 추가를 선택하세요. 패널에는 서버를 추가하는 세 가지 방법이 있습니다. 공식 MCP 레지스트리, URL 기반 원격 서버, 로컬 명령입니다. 로컬 명령 아래에 다음을 채우세요.

  1. 커넥터 이름: Filesystem.
  2. 명령: npx.
  3. 인수: -y @modelcontextprotocol/server-filesystem C:\Users\Public\Documents\Northwind. 끝에는 사용자의 폴더를 넣으세요. -y는 npx가 묻지 않고 패키지를 내려받게 합니다.

환경 변수는 비워 두세요. 이 서버에는 키가 필요 없습니다. 로컬 커넥터 추가를 선택하세요. 커넥터가 중지됨으로 나열됩니다. 시작을 선택하세요.

처음 시작할 때는 npx가 패키지를 내려받느라 조금 더 걸립니다. 그다음 상태가 실행 중으로 바뀌고 서버의 도구가 나열되며, 도구마다 하는 일이 표시됩니다.

읽기만 함 도구는 묻지 않고 실행됩니다. 변경함, 먼저 물어봄 도구는 Conduit에게 기억하라고 하지 않는 한 매번 승인을 묻습니다. Conduit는 이 표시를 서버가 각 도구에 대해 선언한 내용에서 가져옵니다.

Conduit는 콘솔 창 없이 서버를 시작합니다. 명령은 셸을 거치지 않고 직접 실행되므로 여기서 cmd /c 없이도 npx가 작동합니다. Conduit가 이름을 PATH에서 직접 찾아 npx.cmd를 찾아내기 때문입니다.

다음으로 Python 서버를 추가합니다.

3단계 — uvx로 로컬 서버 추가하기

Python 서버도 같은 방식으로 작동하며, 명령만 uvx입니다. 이 단계에서는 웹 페이지를 내려받아 Markdown으로 바꾸는 Fetch 서버를 추가합니다.

커넥터 추가를 다시 선택하세요. 로컬 명령 아래에 이름으로 Fetch, 명령으로 uvx, 인수로 mcp-server-fetch를 입력합니다.

로컬 커넥터 추가를 선택한 다음 시작을 선택하세요. 처음 시작할 때는 서버와 Python 패키지를 내려받느라 몇 초가 걸리고, 커넥터는 fetch라는 도구 하나와 함께 실행 중이 됩니다.

참고: Conduit에는 이미 자체 웹 검색과 페이지 읽기가 있습니다. Fetch는 Python 서버의 예로 넣었을 뿐이며, uvx용으로 배포된 서버라면 어떤 것이든 같은 방식으로 추가합니다.

다음으로 원격으로 실행되는 서버를 추가합니다.

4단계 — 원격 서버 추가하기

원격 서버는 설치할 것이 없습니다. 이 단계에서는 계정이 필요 없는, Microsoft의 공식 문서 검색 서버인 Microsoft Learn을 추가합니다.

원격 서버는 공식 MCP 레지스트리에서 찾을 수 있습니다. 커넥터 추가의 공식 MCP 레지스트리 아래에 단어를 입력하고 검색을 선택하세요.

설치를 선택하면 목록의 서버가 추가됩니다. 레지스트리는 누구에게나 열려 있으므로, 설치하기 전에 서버를 누가 게시했는지 확인하세요. 서버 주소를 안다면 대신 직접 추가할 수도 있습니다. URL 기반 원격 서버 아래에 이름으로 Microsoft Learn, URL로 https://learn.microsoft.com/api/mcp를 입력하세요.

원격 커넥터 추가를 선택한 다음 시작을 선택하세요. 커넥터는 문서 검색, 코드 샘플 찾기, 페이지 읽기용 도구 세 개와 함께 실행 중이 되며, 모두 읽기만 함으로 표시됩니다.

계정이 필요한 원격 서버는 시작하는 대신 로그인 필요로 표시됩니다. 커넥터의 로그인을 선택하고 브라우저에서 로그인을 마치면, Conduit가 받은 접근 권한을 저장합니다.

다음으로 채팅에서 서버를 씁니다.

5단계 — 채팅에서 서버 쓰기

이 단계에서는 커넥터가 답하는 질문을 하고, 이어서 사용자의 승인이 필요한 변경을 요청합니다.

채팅과 새 채팅을 선택하세요. 모델이 필요할 때 커넥터 도구를 찾아볼 수 있게 Conduit가 방법을 주므로, 따로 켜 둘 것이 없습니다. 특정 서버를 쓰게 하는 가장 확실한 방법은 이름을 말하는 것입니다. 다음을 보내세요.

Microsoft Learn 커넥터를 사용해서, 지금 실행 중인 PowerShell 버전을 어떻게 확인하고
Windows 11에서 어떻게 업데이트하는지 알려 주세요. 참고한 페이지의 링크도 달아 주세요.

도구 호출은 답변 속에 한 줄씩 나오며, 커넥터와 도구 이름, 무엇을 요청했는지, 걸린 시간이 보입니다. 호출을 선택하면 정확히 무엇을 보냈고 무엇이 돌아왔는지 볼 수 있습니다. 검색은 읽기만 하므로 묻지 않고 실행되었습니다.

이제 파일을 바꾸는 일을 요청해 보세요. 새 채팅에서 다음을 보내세요.

Filesystem 커넥터를 사용해서, C:\Users\Public\Documents\Northwind의 파일을 나열한 다음,
그 폴더에 reading-list.md라는 파일을 만들어 주세요. 각 PDF를 이름만 보고 짐작한
내용을 한 줄로 설명해서 나열해 주세요.

폴더를 나열하는 것은 읽기만 하므로 실행됩니다. 파일을 쓰는 단계에서는 멈추고 사용자를 기다립니다.

요청에는 도구, 서버가 직접 쓴 도구 설명, 전송될 데이터가 나옵니다. 쓸 경로와 내용도 포함됩니다. 거부를 선택하면 중단됩니다. 이 채팅에서 이 도구를 다시 묻지 않고 실행하게 하려면 이 채팅에서 기억을, 모든 채팅에서 그러려면 이 도구를 항상 허용을 체크한 다음 승인 후 실행을 선택하세요.

이제 파일이 폴더에 있습니다. 기억해 둔 승인을 나중에 확인하거나 거두려면 커넥터 페이지에서 커넥터를 열고 기억된 도구 승인 아래의 해제를 사용하세요.

6단계 — 시작되지 않는 서버 고치기

이 단계에서는 실패한 서버가 어떤 모습이고 왜 그런지 알아내는 방법을 확인합니다.

시작하자마자 종료되는 서버는 Conduit가 확인한 이유와 함께 중단됨으로 표시됩니다.

connector stdout closed (child exited)는 서버가 시작되었다가 종료되었다는 뜻이며, 대개 서버가 출력한 오류가 있습니다. 그 오류를 보려면 같은 명령과 인수를 PowerShell에서 실행해 보세요. 위의 커넥터라면 이렇게 합니다.

npx -y @modelcontextprotocol/server-filesystem C:\Users\Public\Shared Files
Warning: Cannot access directory C:\Users\Public\Shared, skipping
Error: None of the specified directories are accessible

경로에 공백이 있어서 C:\Users\Public\Shared와 Files라는 두 인수로 전달되었고, 둘 다 폴더가 아닙니다. Windows 사용자가 가장 자주 만나는 원인은 다음과 같습니다.

보이는 증상 원인 해결
spawn 'npx' failed Node.js가 설치되어 있지 않거나, 설치하기 전에 Conduit를 시작했습니다. 1단계대로 설치한 다음 Conduit를 완전히 종료했다가 다시 여세요.
명령이 거부됨 명령이 cmd, powershell, wsl 같은 셸입니다. Conduit는 셸을 거쳐 명령을 실행하지 않습니다. 명령에 프로그램 자체를 넣으세요. npx, uvx, node, python, 또는 .exe의 전체 경로입니다.
폴더 인수가 있는데 중단됨 경로에 공백이 있습니다. 인수는 공백마다 나뉩니다. C:\Users\Public\Documents\Projects처럼 경로에 공백이 없는 폴더를 쓰세요.
키가 필요한 서버가 중단됨 키가 없습니다. 서버 문서에 나온 변수 이름으로 환경 변수에 KEY=VALUE 한 줄을 추가하세요.

커넥터의 명령이나 인수를 바꾸려면 새 값으로 다시 추가한 다음, 이전 커넥터를 열고 철회를 선택하세요. 철회하면 커넥터가 중지되고 도구가 꺼집니다.

자주 묻는 질문

MCP 서버를 쓰려면 Node.js와 Python이 필요한가요?

그 언어로 만든 로컬 서버를 쓸 때만 필요합니다. npx로 시작하는 서버에는 Node.js가, uvx로 시작하는 서버에는 자체 Python을 받아 오는 uv가 필요합니다. URL이나 레지스트리로 추가하는 원격 서버는 다른 곳에서 실행되므로 설치할 것이 없습니다. Conduit 자체는 둘 다 필요하지 않습니다.

Claude Desktop의 MCP 설정을 그대로 쓸 수 있나요?

파일을 가져오는 방식은 안 되지만 같은 값을 쓸 수 있습니다. claude_desktop_config.json의 서버마다 command는 명령에, args의 항목은 공백으로 구분해 인수에, env의 각 항목은 KEY=VALUE 한 줄씩 환경 변수에 넣으세요.

API 키가 필요한 원격 서버도 추가할 수 있나요?

OAuth로 로그인하는 서버만 가능합니다. Conduit는 커넥터의 로그인 버튼으로 브라우저를 통해 OAuth로 원격 서버에 로그인하며, 아직 API 키 헤더를 넣는 칸은 없습니다. 로컬로도 실행되는 서버는 대개 키를 환경 변수로 받으므로 환경 변수에 설정할 수 있습니다.

MCP 서버가 내 권한으로 실행되나요?

네. 로컬 서버는 사용자의 컴퓨터에서 실행되는 프로그램이어서 Windows 계정으로 할 수 있는 일은 무엇이든 할 수 있으므로, 알고 있는 출처의 믿을 수 있는 서버만 추가하세요. Conduit는 무언가를 바꾸는 도구를 실행하기 전에 묻지만, 각 도구가 실제로 무엇을 하는지는 서버가 정합니다.

macOS와 Linux에서도 되나요?

네. 커넥터 페이지는 모든 플랫폼에서 같습니다. winget 대신 사용 중인 패키지 관리자로 Node.js와 uv를 설치하고 /Users/you/Documents 같은 경로를 쓰면, 나머지는 튜토리얼 그대로 적용됩니다.

마치며

이 튜토리얼에서는 Node.js와 uv를 설치하고, npx로 로컬 MCP 서버를, uvx로 또 하나를 추가하고, URL로 원격 서버를 추가하고 레지스트리에서 찾는 방법도 살펴보고, 채팅에서 이 서버들을 쓰고, 파일을 쓰는 도구를 승인하고, 시작되지 않는 서버의 원인을 진단했습니다.

명령, 인수, 환경 변수라는 같은 세 칸이면 어떤 로컬 서버든 설정할 수 있으므로, MCP 레지스트리나 프로젝트 README에 있는 서버도 같은 방식으로 설정할 수 있습니다. 더 알아보려면 다음 가이드를 참고하세요.

Conduit 내려받기

Conduit 관련 내용은 최신 릴리스와 일치하며 문서와 소스에서 확인할 수 있습니다. 오류를 발견하셨나요? 알려 주세요. 바로잡겠습니다.

관련 콘텐츠