MCP 서버 Node.js 설치 가이드 — npx 환경 설정부터 첫 실행까지

Q: npx --version은 되는데 MCP 서버가 실행되지 않습니다. 원인이 무엇인가요?

claude_desktop_config.json의 command 경로가 잘못됐을 가능성이 높습니다. which npx 명령으로 절대 경로를 확인하고, 해당 경로를 그대로 입력하세요. nvm으로 Node.js를 설치한 경우 셸마다 경로가 달라질 수 있습니다.

Q: Windows에서도 동일한 방법으로 설치하면 되나요?

Windows에서는 nvm 대신 nvm-windows를 사용하고, 설정 파일 경로도 %APPDATA%\Claude\claude_desktop_config.json입니다. 명령 구분자나 경로 표기가 다를 수 있으므로 공식 문서를 함께 확인하세요.

Q: MCP 서버를 설치할 때 -y 플래그는 왜 붙이나요?

npx -y는 설치 확인 프롬프트를 건너뛰는 옵션입니다. Claude Desktop이 백그라운드에서 npx를 실행할 때 사용자 입력을 받을 수 없으므로 -y를 반드시 붙여야 서버가 정상 시작됩니다.

MCP 서버의 대부분은 Node.js와 npx를 기반으로 배포됩니다. Node.js LTS 버전만 올바르게 설치하면 대부분의 MCP npm 패키지를 npx 한 줄로 바로 실행할 수 있습니다. 이 가이드는 node --version 확인부터 Claude Desktop 설정까지 전 과정을 순서대로 안내합니다. 이미 Node.js가 설치된 분은 2단계 npx 동작 검증부터 읽어도 됩니다.

MCP 서버에 왜 Node.js가 필요한가요?

MCP(Model Context Protocol)는 Claude 같은 AI 어시스턴트가 외부 도구나 데이터 소스에 접근할 수 있게 해주는 개방형 프로토콜입니다. MCP 서버는 다양한 언어로 구현될 수 있지만, npm(Node Package Manager) 생태계를 활용한 Node.js 기반 패키지가 현재 가장 많습니다.

사용자 → Claude Desktop → MCP 서버 (npx 실행) → 외부 도구·API·파일

Claude Desktop은 설정 파일에 등록된 MCP 서버를 자동으로 npx로 실행합니다. 따라서 Node.js와 npx가 올바르게 설치되어 있지 않으면 MCP 서버 자체가 시작되지 않습니다.

Node.js 버전 요구사항

항목	권장	최소
Node.js	LTS (20.x 또는 22.x)	18.x
npm	10.x 이상	9.x
npx	Node.js에 포함	v16 이상 시 자동 포함

준비물

macOS, Linux, 또는 Windows 환경
터미널(Terminal / PowerShell / Command Prompt) 접근 권한
인터넷 연결 (패키지 다운로드)
Claude Desktop 앱 (MCP 서버 사용 목적인 경우)

단계별 설치 방법

단계 1: 현재 Node.js 및 npx 버전 확인

터미널을 열고 다음 명령을 실행합니다.

node --version
npx --version

두 명령 모두 버전 번호(예: v20.11.0, 10.2.4)가 출력되면 이미 설치된 상태입니다. command not found 오류가 나온다면 아직 설치되지 않은 것이므로 다음 단계로 진행하세요.

이미 설치되어 있지만 버전이 낮은 경우: Node.js 18 미만이면 업그레이드를 권장합니다. nvm을 사용하면 손쉽게 전환할 수 있습니다.

단계 2: Node.js LTS 설치 — 방법 선택

설치 방법은 두 가지입니다. 버전 관리가 필요 없다면 공식 설치 방법, 여러 프로젝트에 다른 Node.js 버전이 필요하다면 nvm 방법을 선택하세요.

방법 A — 공식 사이트에서 직접 설치 (간단)

https://nodejs.org 에 접속해 LTS 버튼을 클릭하고 설치 파일을 내려받아 실행합니다. 설치 후 터미널을 새로 열고 node --version으로 확인하세요.

방법 B — nvm으로 설치 (권장)

nvm(Node Version Manager)을 사용하면 LTS 버전을 명령 한 줄로 설치하고 프로젝트마다 버전을 바꿀 수 있습니다.

macOS / Linux nvm 설치:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

설치 후 터미널을 재시작하거나 다음을 실행해 nvm을 활성화합니다.

source ~/.bashrc
# zsh 사용자라면:
source ~/.zshrc

Node.js LTS 설치 및 기본값 설정:

nvm install --lts
nvm use --lts
nvm alias default lts/*

설치 완료 후 확인합니다.

node --version   # 예: v22.2.0
npx --version    # 예: 10.7.0

단계 3: npx 동작 검증

npx가 정상적으로 작동하는지 간단한 패키지로 테스트합니다.

npx --yes cowsay "MCP 준비 완료"

패키지가 다운로드되고 ASCII 소 그림과 함께 메시지가 출력되면 npx 환경이 정상입니다.

단계 4: Claude Desktop 설정 파일 열기

Claude Desktop의 MCP 서버 설정 파일 위치는 운영체제마다 다릅니다.

운영체제	설정 파일 경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json`

파일이 없으면 새로 만들어도 됩니다. 터미널에서 macOS 기준으로 열어봅니다.

open ~/Library/Application\ Support/Claude/claude_desktop_config.json

단계 5: MCP 서버 등록

설정 파일에 원하는 MCP 서버를 등록합니다. 아래는 mcpServers 키 아래에 서버를 추가하는 기본 형식입니다.

{
  "mcpServers": {
    "서버-이름": {
      "command": "npx",
      "args": ["-y", "패키지명"]
    }
  }
}

nvm으로 Node.js를 설치한 경우, Claude Desktop이 셸 환경을 자동으로 읽지 못할 수 있습니다. 이때는 which npx 명령으로 절대 경로를 확인해 입력합니다.

which npx
# 출력 예: /Users/사용자명/.nvm/versions/node/v22.2.0/bin/npx

{
  "mcpServers": {
    "서버-이름": {
      "command": "/Users/사용자명/.nvm/versions/node/v22.2.0/bin/npx",
      "args": ["-y", "패키지명"]
    }
  }
}

단계 6: Claude Desktop 재시작 및 확인

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 시작합니다. 채팅 화면 하단 또는 도구 아이콘에서 MCP 서버 목록이 표시되면 정상적으로 연결된 것입니다.

흔한 오류와 해결 방법

”spawn npx ENOENT” 오류

npx 실행 파일을 찾지 못했다는 의미입니다. 설정 파일의 command 값이 올바른 절대 경로를 가리키는지 확인하세요. nvm 사용자는 which npx로 경로를 재확인합니다.

”Module not found” 또는 패키지 설치 실패

네트워크 문제이거나 패키지명이 틀렸을 가능성이 높습니다. 먼저 터미널에서 직접 같은 명령을 실행해 패키지가 존재하는지 확인합니다.

설정 파일이 JSON 오류라고 나올 때

JSON은 마지막 항목 뒤에 쉼표를 쓰면 오류가 납니다. 아래와 같은 형식을 주의하세요.

{
  "mcpServers": {
    "server-a": { "command": "npx", "args": ["-y", "pkg-a"] },
    "server-b": { "command": "npx", "args": ["-y", "pkg-b"] }
  }
}

마지막 서버 항목 뒤에는 쉼표가 없어야 합니다.

Node.js 기반 한국산 MCP 서버 예시

Node.js 환경이 준비되었다면 devtools 카테고리에서 다양한 MCP 서버를 바로 설치할 수 있습니다. 모두 npx 한 줄로 실행됩니다.

서버	설명	설치 명령
코르독 (KorDoc)	HWP·HWPX·PDF 등 한국 공문서를 Markdown으로 변환	`npx -y kordoc setup`
HWP-MCP (한글 문서 MCP)	AI가 한글(.hwp/.hwpx) 문서를 읽고 편집	`npx -y hwp-mcp`
한포지 (HwpForge)	HWPX 문서를 AI 에이전트가 읽고 쓰고 변환	`npx -y @hwpforge/mcp`

위 서버들의 설치 명령을 단계 5의 args 배열에 그대로 넣으면 바로 사용할 수 있습니다. 더 많은 서버는 전체 서버 목록에서 확인하세요.

자주 묻는 질문

Node.js가 이미 설치되어 있는데도 npx 명령이 없다고 나옵니다. 왜 그런가요?

Node.js v14 이하에서는 npx가 별도 패키지였습니다. v16 이상으로 업그레이드하면 npx가 기본 포함됩니다. nvm use --lts 명령으로 LTS 버전으로 전환해 보세요.

npx —version은 되는데 MCP 서버가 실행되지 않습니다. 원인이 무엇인가요?

claude_desktop_config.json의 command 경로가 잘못됐을 가능성이 높습니다. which npx 명령으로 절대 경로를 확인하고, 해당 경로를 그대로 입력하세요. nvm으로 Node.js를 설치한 경우 셸마다 경로가 달라질 수 있습니다.

nvm과 공식 Node.js 설치 중 어떤 방법이 MCP에 더 적합한가요?

MCP 서버마다 요구하는 Node.js 버전이 다를 수 있으므로, 버전 전환이 편한 nvm을 권장합니다. 단, Claude Desktop은 GUI 앱이라 셸 환경 변수를 자동으로 읽지 못하는 경우가 있으니 설정 파일에 npx 절대 경로를 명시하는 것이 안전합니다.

Windows에서도 동일한 방법으로 설치하면 되나요?

Windows에서는 nvm 대신 nvm-windows를 사용하고, 설정 파일 경로도 %APPDATA%\Claude\claude_desktop_config.json입니다. 명령 구분자나 경로 표기가 다를 수 있으므로 공식 문서를 함께 확인하세요.

MCP 서버를 설치할 때 -y 플래그는 왜 붙이나요?

npx -y는 설치 확인 프롬프트를 건너뛰는 옵션입니다. Claude Desktop이 백그라운드에서 npx를 실행할 때 사용자 입력을 받을 수 없으므로 -y를 반드시 붙여야 서버가 정상 시작됩니다.

Node.js LTS와 Current 버전 중 무엇을 선택해야 하나요?

MCP 서버 생태계는 안정성을 우선하므로 LTS(Long Term Support) 버전을 권장합니다. 2025년 기준 Node.js 20.x 또는 22.x LTS가 안정적입니다.

다음 단계

Node.js와 npx 환경이 준비되었다면 MCP 서버 전체 목록에서 원하는 서버를 찾아 바로 설치해 보세요. 한국어 공문서 처리가 필요하다면 코르독, HWP-MCP, 한포지가 좋은 출발점입니다. 새로운 MCP 서버를 발견했다면 서버 등록 신청도 환영합니다.