왜 MCP 서버가 반드시 파일 (file) 기준의 .env 경로를 사용해야 하는지 알아보세요. Claude Desktop의 설정에는 cwd (현재 작업 디렉토리) 정보가 없으므로 상대 경로를 사용하면 오류가 발생합니다. 해결 방법: os.path.join(os.path.dirname(os.path.abspath(__file__)), '.env').

핵심 요약 (Key Takeaways)

• 왜 MCP 서버가 반드시 파일 (file) 기준의 .env 경로를 사용해야 하는지 알아봅니다.
• Claude Desktop의 설정에는 cwd가 없으므로 상대 경로가 깨집니다.
• 해결 방법: os.path.join(os.path.dirname(os.path.abspath(__file__)), '.env').

문제점: MCP 서버와 예측 불가능한 작업 디렉토리 (Working Directories)

MCP 서버를 구축하고 Claude Desktop 또는 다른 클라이언트에 구성할 때, 일반적으로 command와 args를 지정하지만 cwd를 지정하는 경우는 드뭅니다. 클라이언트는 서버를 서브프로세스 (subprocess)로 실행하며, 이 서브프로세스는 스크립트가 위치한 디렉토리가 아닌 클라이언트의 작업 디렉토리를 상속받습니다.

이는 소리 없는 함정입니다. 만약 서버가 ".env"와 같은 상대 경로로 .env 파일을 로드한다면, 프로세스의 현재 작업 디렉토리 (cwd)가 레포지토리 루트라고 가정하는 것입니다. 코드 내에서 이를 강제하는 것도 없고, 클라이언트 설정에서 이를 보장하는 것도 없습니다.

해결 방법: 파일 (file) 기준으로 .env 경로를 확인하기

가장 견고한 해결책은 .env 경로를 서버 스크립트 자체의 위치에 고정하는 것입니다. Python에서는 다음과 같이 작성합니다:

import os

def load_env(path):
...

핵심 라인에 주목하세요: here = os.path.dirname(os.path.abspath(__file__)). 이 방식은 클라이언트가 프로세스를 어디에서 실행하든 상관없이 작동합니다.

이것이 Claude Code 사용자에게 중요한 이유

아마도 여러분은 MCP 서버를 구축하고 관리하기 위해 Claude Code를 사용하고 계실 것입니다. 만약 .env 파일에서 API 키를 읽어오는 커스텀 MCP 서버를 개발 중이라면, 아마도 저장소(repo) 루트에서 python server.py를 실행하여 테스트했을 것입니다. 그때는 잘 작동했기에 그대로 배포했을 수도 있습니다. 하지만 Claude Desktop(또는 다른 모든 MCP 클라이언트)은 ~나 /Applications 또는 그 외의 다른 위치에서 서버를 실행할 수 있습니다. 그런 상황이 발생하는 순간, 여러분의 서버는 자격 증명(credentials)을 로드하는 데 조용히 실패하게 됩니다.

이러한 실패는 특히 교활합니다. 서버는 정상적으로 시작되지만, API 키가 필요한 모든 도구(tool)가 인증 오류(auth error)를 반환하기 때문입니다. 환경 변수(env vars)가 누락되었다는 사실을 알아차리기 전까지 몇 시간 동안 디버깅을 하게 될 수도 있습니다.

지금 바로 시도해 보세요: MCP 서버 감사(Audit)

1. 모든 MCP 서버 스크립트를 찾으세요 — .env 또는 process.env를 읽는 Python (또는 Node) 파일을 찾으십시오.
2. .env 로딩 코드를 확인하세요 — ".env"와 같은 상대 경로를 사용하고 있습니까? 그렇다면 수정하십시오.
3. Node.js의 경우, '.env' 대신 path.join(__dirname, '.env')를 사용하십시오.
4. 다른 디렉토리에서 테스트해 보세요: cd /tmp && python /path/to/your/server.py — 여전히 환경 변수를 로드합니까? 그렇지 않다면 버그를 찾은 것입니다.

더 깊은 교훈: 암묵적인 가정을 신뢰하지 마세요

이 버그는 더 넓은 원칙의 증상입니다. 즉, 코드가 환경의 현재 작업 디렉토리(current working directory, cwd)에 의존하게 만들지 마십시오. MCP 서버는 여러분이 제어할 수 없는 외부 클라이언트에 의해 실행되기 때문에 특히 취약합니다.

.env 외에도 파일 로깅, SQLite 데이터베이스, 임시 디렉토리 등 서버에서 다른 상대 경로를 사용하는 부분이 있는지 감사하십시오. 이 모든 것들은 __file__을 기준으로 고정되거나 명시적으로 구성되어야 합니다.

결론

단 한 줄의 코드 — os.path.join(os.path.dirname(os.path.abspath(__file__)), ".env") — 로부터 '내 컴퓨터에서는 되는데' 유형의 실패를 근본적으로 방지해 줍니다. 이 코드를 구축하는 모든 MCP 서버에 적용하면, API 키 누락으로 인해 세션을 잃는 일이 다시는 없을 것입니다.

출처: dev.to

원래 게시일: gentic.news