20 September 2025 / AI, MCP, DOTENV

MCP 서버에 dotenv 적용 후 JSON 파싱 에러? 깔끔하게 해결하기

MCP 서버를 개발할 때 API 키나 환경별 설정값 관리를 위해 환경 변수를 사용하는 건 정말 편리한 방법이죠. 특히 .env 파일을 활용하게 해주는 dotenv 라이브러리는 로컬 개발 환경의 필수 동반자라고 할 수 있습니다.

그런데 dotenv를 적용한 MCP 서버를 Gemini CLI나 Claude Desktop 같은 AI 에이전트에 연결했을 때, 혹시 이런 당황스러운 에러 메시지를 만나지 않으셨나요?

SyntaxError: Unexpected token 'd', "[dotenv@17."... is not valid JSON

분명 로컬에서는 잘 돌아갔는데 왜 이러는 걸까요? 오늘은 이 문제의 원인을 파헤치고 깔끔하게 해결하는 방법을 공유해 드리겠습니다.

🤔 문제의 원인: 비밀 요원들의 대화에 끼어든 불청객

MCP 서버가 Gemini CLI와 같은 AI 에이전트와 통신할 때는 표준 입출력(STDIO) 채널을 사용합니다. 이건 마치 둘만 알아들을 수 있는 특별한 언어(JSON)로 대화하는 비밀 요원들과 같아요.

그런데 dotenv는 초기화될 때 자신의 상태 메시지를 표준 출력으로 살짝 내보냅니다. 문제는 이 메시지 역시 비밀 요원들의 대화 채널로 끼어들어간다는 점이죠. AI 에이전트 입장에서는 갑자기 약속되지 않은 이상한 메시지가 날아오니, “이건 우리가 쓰던 JSON 형식이 아닌데?”라며 파싱 에러를 일으키는 것입니다.

Gemini CLI는 너그럽게 에러 메시지만 보여주고 넘어가 주지만, Claude Desktop처럼 깐깐한 친구는 아예 연결조차 거부해 버리니, 이 문제는 꼭 해결해야 합니다.

✨ 해결책: 두 단계로 깔끔하게 해결하기

다행히 이 문제는 아주 간단하게 해결할 수 있습니다. 딱 두 단계만 기억하세요!

첫 번째 단계: dotenv가 조용히 일하도록 만들기

먼저, dotenv가 불필요한 로그를 남기지 않도록 설정해 줍시다. dotenv.config()를 호출할 때 quiet: true 옵션을 추가해 주기만 하면 됩니다. 이렇게 하면 dotenv는 자신의 임무를 조용히, 그리고 완벽하게 수행할 거예요.

import dotenv from "dotenv";

// ...

dotenv.config({ quiet: true }); // quiet: true 옵션을 추가해 조용히 실행되도록 설정

두 번째 단계: 꼭 필요할 때만 dotenv 부르기

사실 .env 파일은 MCP Inspector로 디버깅하는 등 로컬 개발 환경에서만 필요한 경우가 대부분입니다. 실제 AI 에이전트에 연결될 때는 굳이 dotenv를 로드할 필요가 없죠.

DEBUG 같은 특정 환경 변수가 있을 때만 dotenv를 로드하도록 조건을 걸어주면, 불필요한 동작을 막고 더욱 안정적으로 서버를 운영할 수 있습니다.

import dotenv from "dotenv";

// ...

// DEBUG 환경 변수가 'true'일 때만 .env 파일을 로드합니다.
if (process.env.DEBUG === "true") {
  dotenv.config({ quiet: true });
  // 개발자에게 환경 변수가 로드되었음을 알려주는 로그는
  // 표준 '에러' 스트림(stderr)으로 출력하는 것이 좋습니다.
  console.error("💡 .env 파일에서 환경 변수를 성공적으로 불러왔습니다.");
}

이제 디버깅이 필요할 때만 DEBUG=true 환경 변수를 넘겨주면 됩니다. package.json의 inspect 스크립트를 아래와 같이 수정해 볼까요?

// package.json
{
  "scripts": {
    ...
    "inspect": "npm run build && npx @modelcontextprotocol/inspector -e DEBUG=true node build/index.js"
  },
  ...
}

이렇게 하면 npm run inspect 명령을 실행할 때만 .env 파일의 환경 변수가 로드되어 디버깅은 편리하게, 실제 서비스에서는 깔끔하게 동작하는 MCP 서버를 만들 수 있습니다.

마무리하며

이제 여러분의 MCP 서버는 디버깅 시에는 .env 파일의 도움을 받아 편리하게, 실제 AI 에이전트와 연동할 때는 군더더기 없이 깔끔하게 작동할 겁니다. 사소해 보이지만 안정적인 서버 운영의 첫걸음이 되는 팁이니, 꼭 적용해 보시길 바랍니다!