MCP 서버 STDIO 방식 설정 — 로컬 프로세스 연결 구조와 JSON 작성법

Q: command에 npx, uvx, node 중 어느 것을 써야 하나요?

Node.js 기반 패키지는 npx, Python(uv) 기반은 uvx, 직접 빌드한 실행 파일이나 스크립트는 node/python을 씁니다. 각 MCP 서버의 공식 설치 안내를 우선 따르세요.

Q: args 배열에 경로를 넣을 때 백슬래시(\) 처리가 필요한가요?

Windows 환경에서는 JSON 특성상 역슬래시를 이중(\)으로 작성해야 합니다. macOS·Linux는 정방향 슬래시(/)를 그대로 사용하면 됩니다.

Q: env 키를 설정 파일에 넣으면 보안상 문제가 없나요?

claude_desktop_config.json은 로컬 파일이므로 본인 외에 접근하기 어렵지만, API 키처럼 민감한 값은 별도 환경 변수 파일로 분리하거나 시스템 환경 변수로 등록하는 편이 더 안전합니다.

Q: STDIO 서버가 너무 느리게 응답합니다. 어떻게 해야 하나요?

npx는 첫 실행 시 패키지를 내려받아 느릴 수 있습니다. 전역 설치(npm install -g) 후 node 경로를 직접 지정하거나, 자주 쓰는 서버는 로컬에 미리 설치해 두면 응답 속도가 빨라집니다.

MCP 서버를 Claude에 연결하는 방법은 크게 두 가지입니다. 원격 HTTP 서버에 연결하는 SSE 방식과, Claude가 직접 로컬 프로세스를 실행해 통신하는 STDIO 방식입니다. 대부분의 한국산 MCP 서버를 포함한 로컬 서버는 STDIO 방식을 사용합니다. command, args, env 세 가지 JSON 키만 정확히 이해하면, 어떤 STDIO 서버든 Claude Desktop·Claude Code에 안정적으로 연결할 수 있습니다.

STDIO 방식이란 무엇인가

**STDIO(Standard Input/Output)**는 운영체제가 제공하는 가장 기본적인 프로세스 간 통신 방식입니다. MCP에서 STDIO 전송을 선택하면, Claude(호스트 클라이언트)가 설정에 명시된 명령어로 서버 프로세스를 직접 실행하고, 그 프로세스의 표준 입력(stdin)으로 요청을 보내고 표준 출력(stdout)으로 응답을 받습니다. 표준 오류(stderr)는 로그 출력에 사용됩니다.

Claude Desktop / Claude Code
        │
        │  (프로세스 실행: command + args)
        ▼
  MCP 서버 프로세스
  ┌───────────────────────┐
  │  stdin  ← 요청(JSON) │
  │  stdout → 응답(JSON) │
  │  stderr → 로그       │
  └───────────────────────┘

이 구조 덕분에 별도의 포트 개방이나 HTTP 서버 실행 없이, 설정 파일 한 줄만 추가하면 로컬 도구를 Claude에서 바로 사용할 수 있습니다.

SSE 방식과 비교

항목	STDIO	SSE(HTTP)
서버 위치	로컬 프로세스	원격 또는 로컬 HTTP 서버
사전 실행 필요	불필요 (Claude가 실행)	필요 (미리 서버 기동)
네트워크 설정	불필요	포트·방화벽 설정 필요
인증	프로세스 권한	API 키·토큰 등
적합한 용도	로컬 도구, 개인 사용	팀 공유, SaaS 연동
주요 설정 키	`command`, `args`, `env`	`url`, `headers`

개인 워크스테이션에서 한국 문서 처리·로컬 데이터베이스·파일 시스템 도구를 사용하는 경우 대부분 STDIO 방식이 적합합니다.

준비물

Claude Desktop 최신 버전(또는 Claude Code CLI)
Node.js 18 이상 — npx 기반 서버를 사용할 경우
연결할 MCP 서버 패키지 또는 실행 파일
텍스트 편집기(VS Code 권장 — JSON 유효성 검사 지원)

설정 파일 위치

Claude Desktop의 MCP 설정은 아래 경로의 JSON 파일에서 관리합니다.

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

Claude Code(CLI)를 사용한다면 프로젝트 루트의 .claude/mcp.json 또는 전역 설정 파일에 동일한 구조로 작성합니다.

STDIO 설정 JSON 구조

mcpServers 객체 안에 각 서버를 키-값으로 등록합니다. STDIO 서버의 필수 키는 command와 args이며, 환경 변수가 필요하면 env를 추가합니다.

{
  "mcpServers": {
    "서버-이름": {
      "command": "실행할-명령어",
      "args": ["인수1", "인수2"],
      "env": {
        "환경변수명": "값"
      }
    }
  }
}

command 키

command는 운영체제가 실행할 바이너리 또는 명령어입니다. 자주 쓰이는 값은 다음과 같습니다.

값	설명
`npx`	npm 레지스트리의 Node.js 패키지를 즉시 실행
`node`	직접 Node.js 스크립트 파일 실행
`uvx`	uv(Python 패키지 매니저)로 패키지 실행
`python` / `python3`	Python 스크립트 직접 실행
`/절대/경로/바이너리`	직접 빌드한 실행 파일

npx를 사용하면 패키지 설치 없이 최신 버전을 바로 실행할 수 있어 편리합니다. 단, 첫 실행 시 패키지 다운로드 시간이 걸립니다.

args 키

args는 command에 전달하는 인수 배열입니다. 문자열 배열로 작성하며, 공백이 포함된 경로도 배열 원소로 분리하면 처리됩니다.

"args": ["-y", "패키지명"]

npx의 경우 -y 플래그는 설치 확인 프롬프트를 건너뜁니다. 서버 측 인수(포트, 설정 파일 경로 등)도 이 배열에 이어서 추가합니다.

env 키

env는 해당 프로세스에만 적용되는 환경 변수를 지정합니다. API 키, 파일 경로, 언어 설정 등을 주입할 때 사용합니다.

"env": {
  "LANG": "ko_KR.UTF-8",
  "MY_API_KEY": "여기에-키-값"
}

env를 생략하면 Claude Desktop의 환경을 그대로 상속합니다.

실전 예시 — 한국 MCP 서버 설정

MCP모아의 개발도구 카테고리에는 STDIO 방식으로 동작하는 다양한 한국산 서버가 등록되어 있습니다. 아래 세 서버를 예시로 실제 설정 파일을 작성해 보겠습니다.

코르독(KorDoc) — 한국 공문서 변환

코르독은 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환하는 서버입니다. GitHub 저장소: https://github.com/chrisryugj/kordoc

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    }
  }
}

HWP-MCP — 한글 문서 읽기·편집

HWP-MCP는 AI 어시스턴트가 .hwp/.hwpx 파일을 읽고 편집·생성할 수 있게 해주는 서버입니다. GitHub 저장소: https://github.com/treesoop/hwp-mcp

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

한포지(HwpForge) — HWPX AI 에이전트 연동

한포지는 HWPX 문서를 AI 에이전트가 읽고 쓰고 변환할 수 있게 해주는 서버로, 한컴 한글 HWPX(KS X 6101) 표준을 지원합니다. GitHub 저장소: https://github.com/ai-screams/HwpForge

{
  "mcpServers": {
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

세 서버를 한꺼번에 등록하는 전체 예시

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    },
    "hwpforge": {
      "command": "npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료 후 재시작해야 변경 사항이 반영됩니다.

흔한 오류와 해결 방법

STDIO 설정에서 자주 발생하는 문제와 해결 방법을 정리했습니다.

오류 증상	원인	해결 방법
서버가 목록에 안 나타남	JSON 문법 오류	온라인 JSON 유효성 검사기로 확인 후 재시작
”command not found”	npx·node 경로 불인식	절대 경로 사용 (예: `/usr/local/bin/npx`)
서버 실행 후 바로 종료	패키지 오류 또는 의존성 문제	stderr 로그 확인 (`~/Library/Logs/Claude/` macOS)
응답이 매우 느림	npx가 매번 패키지 다운로드	전역 설치 후 node 절대 경로로 변경
한글 깨짐	인코딩 환경 변수 미설정	`env`에 `"LANG": "ko_KR.UTF-8"` 추가
Windows에서 경로 오류	역슬래시 이스케이프 누락	`\\` 대신 `/` 또는 `\\\\` 사용

Claude Desktop 로그 확인 방법

macOS에서는 아래 경로에서 실시간 로그를 확인할 수 있습니다.

tail -f ~/Library/Logs/Claude/mcp*.log

로그에서 stderr 출력을 보면 서버가 왜 실패했는지 바로 파악할 수 있습니다.

다음 단계

STDIO 방식의 기본 원리를 익혔다면, 이제 본인의 용도에 맞는 서버를 찾아 연결해 보세요. MCP모아 전체 서버 목록에서 카테고리별로 검색하거나, 개발도구 카테고리에서 개발 생산성을 높여주는 서버를 골라볼 수 있습니다.

직접 만든 MCP 서버를 등록하고 싶다면 서버 등록 페이지에서 신청할 수 있습니다.

자주 묻는 질문

STDIO와 SSE 방식의 가장 큰 차이는 무엇인가요?

STDIO는 Claude가 직접 로컬 프로세스를 실행해 stdin/stdout으로 통신하므로 별도 서버 실행이 필요 없습니다. SSE는 HTTP로 원격 서버에 연결하기 때문에 서버가 미리 실행 중이어야 합니다. 로컬에서 혼자 쓸 때는 STDIO가 훨씬 간편합니다.

command에 npx, uvx, node 중 어느 것을 써야 하나요?

Node.js 기반 패키지는 npx, Python(uv) 기반은 uvx, 직접 빌드한 실행 파일이나 스크립트는 node·python을 씁니다. 각 MCP 서버의 공식 설치 안내를 우선 따르세요.

args 배열에 경로를 넣을 때 백슬래시 처리가 필요한가요?

Windows 환경에서는 JSON 특성상 역슬래시를 이중으로 작성해야 합니다. macOS·Linux는 정방향 슬래시를 그대로 사용하면 됩니다.

env 키를 설정 파일에 넣으면 보안상 문제가 없나요?

claude_desktop_config.json은 로컬 파일이므로 본인 외에 접근하기 어렵지만, API 키처럼 민감한 값은 별도 환경 변수 파일로 분리하거나 시스템 환경 변수로 등록하는 편이 더 안전합니다.

설정을 저장했는데 Claude Desktop에서 서버가 나타나지 않습니다.

Claude Desktop을 완전히 종료한 뒤 다시 시작해야 변경 사항이 반영됩니다. JSON 문법 오류(쉼표 누락, 괄호 불일치)가 없는지도 확인하세요.

STDIO 서버가 너무 느리게 응답합니다. 어떻게 해야 하나요?

npx는 첫 실행 시 패키지를 내려받아 느릴 수 있습니다. 전역 설치(npm install -g) 후 node 경로를 직접 지정하거나, 자주 쓰는 서버는 로컬에 미리 설치해 두면 응답 속도가 빨라집니다.