기상청 Open API를 활용한 날씨 MCP 서버를 만들어보자. (3)

Claude Desktop에 MCP 서버 연동 방법

Claude Desktop에 MCP(Model Context Protocol) 서버를 연동하는 과정은 Anthropic의 MCP 프레임워크를 활용하여 외부 도구, 리소스, 프롬프트를 Claude와 통합하는 작업입니다.

전제 조건

• Claude Desktop 설치: 최신 버전의 Claude Desktop 애플리케이션이 설치되어 있어야 합니다. Anthropic의 공식 웹사이트에서 다운로드 가능합니다.
• MCP 서버 준비: 연동하려는 MCP 날씨 서버가 준비되어 있어야 합니다.
• 기본적인 CLI 지식: 터미널에서 명령어를 실행할 수 있는 기본적인 이해가 필요합니다.

---

1. Claude Desktop 설정 파일 구성

Claude Desktop은 MCP 서버와의 연결 정보를 설정 파일에서 읽습니다. 설정 파일은 JSON 형식으로, 일반적으로 사용자 홈 디렉터리의 특정 경로에 위치합니다.

2.1. 설정 파일 위치 확인

아래 명령어를 프로젝트의 홈에서 실행하여 설정 정보를 추가해 줍니다.

mcp install src/server.py

만약 실행시 오류가 발생하였다면 파일이 없거나 아래 설정 정보가 없기떄문입니다. 설정정보를 추가 및 저장하고 위의 명령어를 다시 실행합니다.

vi ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 추가하기
{
  "mcpServers": [
  ]
}

2.2. 설정 파일 확인

설정 파일을 열어보면 방금 명령어로 실행한 MCP 서버 정보를 추가되어 있을 것입니다. 다만, 그대로 사용하면 오류가 발생할 수 있으니 변경후 코드로 적용해주세요.
command에는 uv 명령어의 절대 경로로 변경합니다.
directory에는 py-mcp-ko-weather 프로젝트의 절대 경로로 변경합니다.

# 변경전
{
    "mcpServers": {
        "Korea Weather": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "mcp[cli]",
                "mcp",
                "run",
                "/Users/jikime/src/cookai.dev/oh-my-agent/mcp-tools/py-mcp-ko-weather/src/server.py"
            ]
        }
    }
}

# 변경후
{
  "mcpServers": {
      "Korea Weather": {
        "command": "/Users/jikime/.local/bin/uv",
        "args": [
            "--directory",
            "/Users/jikime/src/cookai.dev/oh-my-agent/mcp-tools/py-mcp-ko-weather",
            "run",
            "src/server.py"
        ]
    }
  }
}

• 필드 설명:
  • name: 서버의 고유 이름(임의로 지정 가능).
  • command: 서버를 실행하는 명령어(예: npx, uv).
  • args: 명령어에 전달할 인자 배열.

---

3. Claude Desktop에서 MCP 서버 실행

설정 파일을 저장한 후, Claude Desktop을 실행하여 MCP 서버를 시작합니다.

3.1. Claude Desktop 실행

Claude Desktop을 실행하면, 설정 파일에 명시된 MCP 서버가 자동으로 시작됩니다.

3.2. 서버 실행 확인

• Claude Desktop은 mcpServers에 명시된 command와 args를 실행하여 서버를 시작합니다.
• 터미널에서 서버 로그를 확인하려면, Claude Desktop을 디버그 모드로 실행하거나, 서버 자체를 독립적으로 실행하여 로그를 확인합니다:
• uv run src/server.py
• 정상적으로 실행되면, 서버는 JSON-RPC 요청을 수신할 준비가 됩니다. 그리고 아래 이미지처럼 도구모양의 아이콘이 생기고 클릭시 2개의 도구 목록을 확인할 수 있습니다.

 

---

4. MCP 서버와의 연결 테스트

Claude Desktop이 MCP 서버와 제대로 연결되었는지 확인하려면, 도구 호출을 테스트합니다.

4.1. 도구 요청

1. Claude Desktop을 열고 대화 창에 도구와 관련된 질문을 입력합니다. 예를 들어, 날씨 서버를 연동했으니: 
2. 서울특별시 서초구 서초1동의 날씨를 알려줘.
3. Claude는 내부적으로 MCP 서버의 도구(예: get_grid_location, get_forecast)를 호출하여 결과를 가져옵니다.

4.2. 권한 요청 확인

• MCP 서버의 도구를 처음 호출할 때, Claude Desktop은 사용자에게 도구 사용 허가를 요청하는 팝업을 표시합니다.
• 예: "Korea Weather 도구를 허용하시겠습니까?"
• 허가를 승인하면 도구가 실행됩니다.

 

4.3. 결과 확인

• 서버가 결과를 반환하면, Claude는 이를 대화 컨텍스트에 통합하여 사용자에게 응답합니다.

---

5. 디버깅 및 문제 해결

연동 과정에서 문제가 발생할 수 있습니다. 아래는 일반적인 문제와 해결 방법입니다.

5.1. 서버가 시작되지 않음

• 증상: Claude Desktop에서 도구 호출이 실패하거나 응답이 없음.
• 해결:
  • 설정 파일의 command와 args가 올바른지 확인.
  • 터미널에서 command와 args를 직접 실행하여 서버가 정상 작동하는지 확인:

    /Users/jikime/.local/bin/uv --directory /Users/jikime/src/cookai.dev/oh-my-agent/mcp-tools/py-mcp-ko-weather run src/server.py

5.2. 도구 목록이 표시되지 않음

• 증상: Claude가 MCP 서버의 도구를 인식하지 못함.
• 해결:
  • 서버가 JSON-RPC 프로토콜을 준수하는지 확인.
  • 서버 로그를 확인하여 /tools 엔드포인트가 올바르게 응답하는지 점검.

5.3. 권한 문제

• 증상: 도구 호출 시 권한 요청 팝업이 반복됨.
• 해결:
  • Claude Desktop의 설정에서 MCP 서버에 대한 권한을 영구적으로 승인.
  • 설정 파일에서 name 필드가 고유한지 확인(중복된 이름은 충돌을 일으킬 수 있음).