클로드 데스크탑 MCP 설정 가이드: 파이썬으로 Naver 검색 서버 연동 방법

안녕하세요! 오늘은 Anthropic의 강력한 AI 모델인 Claude를 데스크톱 앱으로 사용하면서, 외부 데이터 소스나 기능을 연동할 수 있게 해주는 MCP(Model Context Protocol)를 활용하는 방법을 공유하고자 합니다.

특히, Python으로 직접 만든 Naver 검색 API용 MCP 서버를 Claude 데스크톱 앱에 성공적으로 연결하기까지의 과정과, 그 과정에서 마주쳤던 여러 오류들(JSON 오류, 경로 문제, 의존성 누락, API 키 인증 실패 등)을 해결한 경험을 상세히 담았습니다.

목표: Claude 데스크톱 앱에서 "분당 맛집 찾아줘" 같은 질문을 하면, 직접 만든 Naver 검색 MCP 서버를 통해 실시간 검색 결과를 받아 답변하도록 만들기

준비물:

1. Python 실행 환경: 최신 Python 버전과 uv (Python 패키지 설치 및 가상 환경 관리 도구, pip install uv로 설치) 사용을 권장합니다.
2. Claude 데스크톱 앱: Claude 공식 웹사이트에서 다운로드하여 설치합니다. (현재 베타 버전일 수 있습니다.)
3. Naver Developers 계정 및 API 키:
   • Naver Developers에서 애플리케이션을 등록합니다.
   • 등록된 애플리케이션에서 "검색" API를 사용하도록 설정합니다.
   • 애플리케이션 정보에서 Client ID와 Client Secret 값을 확인하고 기록해 둡니다.
4. MCP 서버 코드: Naver 검색 API를 MCP 서버로 구현한 Python 코드. (이 글에서는 예시로 직접 만드신 pfldy2850/py-mcp-naver 프로젝트를 기반으로 설명합니다.)
5. 텍스트 편집기: VS Code, Notepad++ 등 (JSON 및 Python 코드 편집용)

---

1단계: 프로젝트 설정 및 코드 준비

먼저, MCP 서버 코드를 로컬 환경에 준비합니다.

1. 프로젝트 클론: 터미널을 열고 원하는 위치에 프로젝트 코드를 복제합니다.

   git clone [https://github.com/pfldy2850/py-mcp-naver.git](https://github.com/pfldy2850/py-mcp-naver.git)
   cd py-mcp-naver

2. pyproject.toml 확인 및 수정: 프로젝트 루트에 있는 pyproject.toml 파일을 열어 의존성을 확인합니다.
   • 중요: 이 프로젝트는 원래 fastmcp라는 라이브러리를 사용했지만, 이 라이브러리는 deprecated 되었습니다. 대신 공식 mcp 패키지를 사용해야 합니다.
   • [project.dependencies] 섹션에 fastmcp가 있다면 삭제하고, mcp[cli] 와 서버 코드에 필요한 다른 라이브러리(httpx, xmltodict, pydantic 등)가 포함되어 있는지 확인/추가합니다.

       [project]
       # ...
       requires-python = ">=3.10"
       dependencies = [
         "mcp[cli]>=0.1.0", # 공식 SDK 패키지 (버전은 최신 확인)
         "httpx>=0.28.1",
         "pydantic>=2.10.6",
         "xmltodict>=0.14.2",
         # "fastmcp>=..." # 이 줄은 삭제 또는 주석 처리
       ]
       # ...

3. 의존성 설치: uv를 사용하여 필요한 라이브러리들을 설치합니다.

   uv sync --dev --all-extras

   (이 과정에서 fastmcp가 삭제되고 mcp가 설치되는 로그를 확인했습니다.)
4. server.py Import 경로 수정: src/server.py 파일을 열어 fastmcp를 import하는 부분을 공식 SDK 경로로 수정합니다.
   • 변경 전: from fastmcp import FastMCP
   • 변경 후: from mcp.server.fastmcp import FastMCP
   • 파일을 저장합니다.

---

2단계: 초기 테스트 및 문제 해결 여정

이제 서버를 실행하고 Claude와 연동을 시도하며 발생했던 문제들을 살펴봅니다.

시도 1: 공식 SDK의 mcp install 사용 (실패)

• 공식 문서에 따라 mcp install 명령어를 시도했습니다.

    # 환경 변수 설정 후 (set 또는 $env:)
    uv run mcp install src/server.py -v NAVER_CLIENT_ID=... -v NAVER_CLIENT_SECRET=... --name "naver-mcp"

• 결과: Claude 앱을 재시작했지만 여전히 "Server disconnected" 오류 발생. 
• 분석: Claude 설정(image_fe8e18.png)을 보니 mcp install이 등록한 실행 명령(uv run --with mcp[cli] mcp run ...)이 복잡하고, workingDirectory를 제대로 고려하지 못해 FileNotFoundError 를 유발하는 것으로 추정되었습니다. (로그에서 Claude 앱 설치 경로 내부의 파일을 찾으려는 시도 확인)

시도 2: claude_desktop_config.json 수동 설정 (여러 차례 실패)

 

 

• mcp install 대신 설정을 직접 제어하기로 하고 claude_desktop_config.json 파일을 수정했습니다. (경로: %APPDATA%\Claude)
• 겪었던 문제들:

• 

   
  1. JSON 문법 오류:
     • 편집 과정에서 후행 쉼표(Trailing comma) 를 넣거나, 복사-붙여넣기 시 보이지 않는 특수 문자 (혻) 가 포함되어 (C:\...\type claude_desktop_config.json 출력 결과) "Expected property name or '}'..." 오류가 계속 발생했습니다.
     • 해결: JSON 내용을 완전히 삭제 후, 문법에 맞는 깨끗한 코드를 붙여넣고 UTF-8(BOM 없음) 인코딩으로 저장하여 해결했습니다.

       

  2. FileNotFoundError (경로 오류):
     • JSON 문법 오류 해결 후에도 "Server disconnected"가 지속되었고, 로그 확인 결과 FileNotFoundError 가 발생했습니다 (2025-03-26T15:15:... 로그).
     • 처음에는 args에 상대 경로(src\\server.py)를 사용했으나 workingDirectory 설정이 무시되는 듯하여, 절대 경로(C:\\...\\server.py)로 변경했습니다.
     • 하지만 절대 경로에서도 src 폴더를 누락하여 (C:\\...\\py-mcp-naver-main\\server.py로 잘못 지정) 여전히 파일을 찾지 못했습니다.
     • 해결: server.py의 정확한 절대 경로 (C:\\...\\py-mcp-naver-main\\src\\server.py) 를 args에 지정하여 해결했습니다.
  3. ModuleNotFoundError: No module named 'xmltodict':
     • 경로 문제 해결 후, 이번에는 xmltodict 모듈을 찾을 수 없다는 오류가 발생했습니다 (2025-03-26T15:19:... 로그). pyproject.toml에 있었고 uv sync도 했지만, Claude가 사용하는 환경에는 설치되지 않은 문제였습니다.
     • 해결: 터미널에서 uv sync를 다시 실행하고, 만약을 위해 uv pip install xmltodict를 명시적으로 실행하여 의존성을 확실히 설치했습니다. (image_fe09fc.png 작업 후)
  4. 401 Unauthorized (API 키 인증 실패):
     • 모듈 문제 해결 후, 실제 도구를 사용하려 하자 이번에는 Naver API에서 401 Unauthorized 오류가 발생했습니다 
     • 해결: Naver Developers 웹사이트에서 Client ID와 Secret 값이 정확한지, 검색 API 사용 권한이 있는지 확인하고, 올바른 값으로 claude_desktop_config.json의 env 섹션을 수정하여 해결했습니다.

     • 

 

---

3단계: 최종 작동 확인 및 설정

위 모든 문제들을 해결하고 아래와 같은 최종 claude_desktop_config.json 설정에 도달했습니다.

{
  "mcpServers": {
    "naver-mcp": {
      "command": "uv", // uv 사용
      "args": [
        "run",
        "python",
        // server.py의 정확한 절대 경로 (src 포함)
        "C:\\Users\\user\\Downloads\\py-mcp-naver-main\\src\\server.py" 
      ],
      // 프로젝트 루트를 작업 디렉토리로 지정
      "workingDirectory": "C:\\Users\\user\\Downloads\\py-mcp-naver-main", 
      "env": {
        // Naver Developers에서 발급받은 정확한 키 값
        "NAVER_CLIENT_ID": "YOUR_NAVER_CLIENT_ID", 
        "NAVER_CLIENT_SECRET": "YOUR_NAVER_CLIENT_SECRET" 
      }
    }
  }
}

(실제 경로와 키 값은 본인 환경에 맞게 수정해야 합니다.), 그리고 //는 삭제하셔야 합니다. json에서 호환되지 않습니다.

이 설정을 적용하고 Claude 데스크톱 앱을 재시작하자, 드디어! Claude가 naver-mcp 서버에 성공적으로 연결하고 search_local, search_blog 등의 도구를 사용하여 Naver 검색 결과를 가져오는 것을 확인할 수 있었습니다. 

---

결론

Claude 데스크톱 앱에 커스텀 MCP 서버를 연동하는 과정은 생각보다 순탄치 않았습니다. 특히 공식 SDK 문서와 실제 동작 간의 미묘한 차이(fastmcp 인터페이스 유지), mcp install의 불안정성, 설정 파일(claude_desktop_config.json)의 민감성(JSON 문법, workingDirectory 동작 방식), 실행 환경의 의존성 문제 등 여러 난관이 있었습니다.

핵심 해결 과정 요약:

1. 공식 mcp[cli] 패키지 사용: Deprecated된 fastmcp 대신 공식 SDK를 설치합니다.
2. server.py Import 경로 수정: from mcp.server.fastmcp import ... 로 변경합니다.
3. claude_desktop_config.json 수동 설정:
   • mcp install 대신 설정을 직접 편집합니다.
   • command는 uv, args는 ["run", "python", "서버파일_절대경로"] 형식 사용합니다.
   • workingDirectory를 반드시 프로젝트 루트로 지정합니다.
   • env에 API 키 등 환경 변수를 정확히 넣습니다.
   • JSON 문법 오류 및 **파일 인코딩(UTF-8)**에 극도로 주의합니다.
4. 의존성 확인: uv sync 및 필요시 uv pip install <패키지>로 Claude 실행 환경에 필요한 모든 라이브러리가 설치되었는지 확인합니다.
5. API 키 확인: 외부 API 사용 시 인증 정보(키, 권한 등)가 올바른지 확인합니다.
6. 로그 적극 활용: 문제가 발생하면 Claude 설정의 "로그 폴더 열기"를 통해 mcp-server-stderr.log 등 관련 로그를 확인하여 오류 원인을 추적합니다.

이 글이 Claude 데스크톱 앱과 MCP를 활용하여 자신만의 AI 에이전트나 도구를 구축하려는 분들께 조금이나마 도움이 되기를 바랍니다!