MCP 서버 환경변수 설정 — API 키 보안 관리 및 env 항목 작성법

MCP 서버를 Claude Desktop에 연결할 때 가장 자주 막히는 단계가 바로 API 키 등록입니다. 설정 파일 claude_desktop_config.json의 env 항목에 키와 값을 올바르게 입력하면 MCP 서버가 외부 API를 인증하고 기능을 제공합니다. 이 글에서는 환경변수 작성 구조부터 보안 주의사항, 흔한 오류 해결까지 한 번에 정리합니다.

왜 env 항목이 필요한가

MCP 서버는 Claude Desktop이 실행하는 별도 프로세스입니다. 서버가 외부 API(예: 기상청, DART 전자공시, 지도 서비스 등)를 호출하려면 인증 키가 필요한데, 이 키를 코드에 직접 박아 넣으면 코드 공유·버전 관리 시 유출 위험이 생깁니다. 그 대신 실행 시점에 환경변수로 주입하면 키 값을 코드와 분리할 수 있습니다.

Claude Desktop은 각 MCP 서버를 mcpServers 블록에 정의할 때 env 객체를 함께 지정하도록 설계되어 있습니다. 이 값들은 해당 서버 프로세스가 시작될 때 환경변수로 주입되며, 서버 코드에서는 process.env.MY_API_KEY(Node.js)나 os.environ["MY_API_KEY"](Python) 형태로 읽어 사용합니다.

Claude Desktop
    │
    ├─ spawn ──► MCP 서버 프로세스
    │               (env 주입: API_KEY=...)
    │
    └──────────────────────────► 외부 API / 한국 서비스

설정 파일 위치

먼저 운영체제별 설정 파일 경로를 확인합니다.

운영체제	경로
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux (비공식)	~/.config/Claude/claude_desktop_config.json

파일이 없다면 Claude Desktop을 한 번 실행한 후 자동 생성됩니다. 텍스트 편집기(VS Code, 메모장 등)로 직접 열어 편집합니다.

단계별 env 항목 작성법

1단계 — 설정 파일 기본 구조 확인

claude_desktop_config.json은 다음과 같은 JSON 구조입니다.

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

mcpServers 아래에 서버별 블록이 오고, 각 블록 안에 command·args·env를 작성합니다.

2단계 — env 항목에 API 키 등록

env 객체 안에 "환경변수명": "값" 형식으로 입력합니다. 환경변수명은 보통 대문자와 밑줄로 작성합니다.

{
  "mcpServers": {
    "my-api-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-package"],
      "env": {
        "MY_API_KEY": "여기에-발급받은-실제-키-값을-입력"
      }
    }
  }
}

여러 환경변수가 필요하다면 쉼표로 구분하여 나열합니다.

{
  "mcpServers": {
    "multi-key-server": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": {
        "API_KEY": "your-api-key-here",
        "API_SECRET": "your-secret-here",
        "BASE_URL": "https://api.example.com"
      }
    }
  }
}

3단계 — 여러 서버를 동시에 등록하는 경우

실무에서는 여러 MCP 서버를 함께 사용하는 경우가 많습니다. 각 서버를 독립된 블록으로 나란히 작성합니다.

{
  "mcpServers": {
    "server-a": {
      "command": "npx",
      "args": ["-y", "package-a"],
      "env": {
        "SERVICE_A_KEY": "key-for-a"
      }
    },
    "server-b": {
      "command": "npx",
      "args": ["-y", "package-b"],
      "env": {
        "SERVICE_B_KEY": "key-for-b"
      }
    }
  }
}

4단계 — Claude Desktop 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료합니다. macOS에서는 메뉴바 아이콘까지 종료(Quit)하고, Windows에서는 트레이 아이콘 우클릭 후 종료합니다. 이후 다시 실행하면 변경된 설정이 적용됩니다.

5단계 — 연결 상태 확인

Claude Desktop 화면 하단 또는 채팅 입력창 근처에 MCP 서버 연결 아이콘이 나타납니다. 연결에 성공하면 해당 서버의 도구(tool)를 Claude가 인식합니다. Claude에게 “현재 사용 가능한 도구를 알려줘”라고 물어보면 등록된 서버 기능 목록을 확인할 수 있습니다.

6단계 — 보안 강화 조치

API 키가 포함된 설정 파일은 외부에 노출되지 않도록 관리해야 합니다.

# macOS/Linux: 소유자만 읽고 쓸 수 있도록 권한 설정
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json

Git을 사용한다면 .gitignore에 설정 파일을 추가합니다.

# .gitignore 예시
claude_desktop_config.json

API 키가 필요 없는 서버의 env 처리

모든 MCP 서버가 API 키를 요구하지는 않습니다. 예를 들어 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)는 한글 문서를 처리하는 서버로, 별도 API 키 없이 동작합니다. 이 경우 env 항목 자체를 생략하거나 빈 객체로 두어도 됩니다.

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

설치 명령은 각 서버의 공식 저장소(kordoc GitHub, hwp-mcp GitHub, HwpForge GitHub)에서 확인하세요.

흔한 오류와 해결 방법

실제 설정 과정에서 자주 마주치는 문제를 정리했습니다.

증상	원인	해결 방법
MCP 서버가 목록에 보이지 않음	Claude Desktop 미재시작	완전 종료 후 재실행
JSON 파싱 오류	쉼표 누락 또는 따옴표 불일치	JSON 유효성 검사기 사용
인증 실패(401/403)	API 키 값 오타 또는 만료	발급 서비스에서 키 재확인
환경변수가 서버에 전달 안 됨	env 블록이 잘못된 위치에 작성됨	mcpServers 해당 서버 블록 안에 위치 확인
서버 실행 자체가 안 됨	command 또는 args 오류	터미널에서 동일 명령 직접 실행 후 오류 확인

JSON 유효성 검사 방법

설정 파일을 수정한 뒤 터미널에서 다음 명령으로 문법을 빠르게 확인할 수 있습니다.

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

오류가 없으면 정리된 JSON이 출력됩니다. 오류가 있으면 어느 줄에 문제가 있는지 알려줍니다.

환경변수 관리 모범 사례

보안을 유지하면서 편리하게 관리하는 방법을 정리했습니다.

키 이름 규칙을 일관되게 정합니다. 서비스명을 접두사로 붙이면 어떤 서비스의 키인지 한눈에 알 수 있습니다.

좋은 예: NAVER_MAP_API_KEY, KAKAO_REST_API_KEY, DART_API_KEY
나쁜 예: KEY, MYKEY, K1

키 교체 주기를 정해 정기적으로 갱신합니다. API 키가 노출되었다고 의심될 때는 즉시 해당 서비스 콘솔에서 키를 폐기하고 새로 발급받은 뒤 설정 파일을 업데이트하세요.

백업 시 주의: 설정 파일을 클라우드 드라이브에 자동 동기화하는 경우 API 키도 함께 업로드됩니다. 민감한 정보가 포함된 파일은 동기화 제외 목록에 추가하거나, 키 값 부분을 비워둔 템플릿 파일만 별도 보관하는 방식을 권장합니다.

다음 단계

환경변수 설정이 완료되면 개발자 도구(devtools) 카테고리에서 다양한 MCP 서버를 탐색해 보세요. 한글 문서를 다루는 코르독(KorDoc)이나 HWP-MCP처럼 API 키 없이 바로 사용 가능한 서버부터 시작하면 환경 구성을 검증하기 좋습니다. 더 많은 한국 특화 MCP 서버는 전체 서버 목록에서 확인하실 수 있습니다.

자주 묻는 질문

MCP 서버 환경변수는 어디에 입력하나요?

Claude Desktop 설정 파일(claude_desktop_config.json)의 각 서버 항목 안에 env 객체를 추가하고, "KEY": "VALUE" 형식으로 입력합니다. 설정 파일 경로는 macOS의 경우 ~/Library/Application Support/Claude/, Windows의 경우 %APPDATA%\Claude\ 폴더 안에 있습니다.

API 키를 환경변수 없이 바로 명령줄 인수로 넘겨도 되나요?

기술적으로는 가능하지만, args 배열에 직접 입력하면 프로세스 목록에서 키 값이 노출될 위험이 있습니다. 항상 env 항목을 사용하는 것을 권장합니다.

claude_desktop_config.json을 git에 커밋해도 되나요?

안 됩니다. API 키가 포함된 설정 파일은 절대 버전 관리 시스템에 올려서는 안 됩니다. .gitignore에 해당 파일을 추가하거나, 민감 정보를 포함하지 않는 별도 템플릿 파일만 공유하세요.

환경변수를 추가했는데 MCP 서버가 여전히 연결이 안 됩니다. 무엇을 확인해야 하나요?

가장 먼저 Claude Desktop을 완전히 종료(트레이 아이콘까지 종료)하고 다시 실행해 보세요. 그래도 안 된다면 JSON 문법 오류(쉼표 누락, 따옴표 불일치 등)를 확인하고, API 키 값 자체가 유효한지 발급 서비스에서 재확인하세요.

API 키가 필요 없는 MCP 서버도 env 항목을 작성해야 하나요?

API 키가 필요 없는 서버는 env 항목 자체를 생략해도 됩니다. 코르독(KorDoc), HWP-MCP, 한포지(HwpForge) 등은 별도 API 키 없이 동작하므로 env 블록이 필요하지 않습니다.

여러 MCP 서버에 같은 환경변수를 등록해야 할 때 중복 입력 외에 다른 방법이 있나요?

현재 Claude Desktop은 서버별로 독립된 env 블록을 사용하므로 같은 값이라도 각 서버 항목에 반복 입력해야 합니다. 운영체제 수준의 환경변수로 미리 설정해 두면, 일부 MCP 서버는 시스템 환경변수를 자동으로 상속받기도 합니다.