차세대 AI 연결 기술: 30분 만에 나만의 MCP 서버 구축하기

인공지능 모델의 진화는 빠르게 진행되고 있지만, 아직 한 가지 큰 제약이 있습니다. 바로 외부 데이터와의 연결입니다. 클로드(Claude)나 GPT와 같은 최신 AI 모델들은 뛰어난 텍스트 생성 능력을 갖고 있지만, 실시간 데이터에 접근하거나 외부 시스템과 상호작용하는 능력이 제한적입니다.

이런 문제를 해결하기 위해 Anthropic에서 Model Context Protocol(MCP)을 개발했습니다. MCP는 AI 모델이 외부 데이터 소스나 도구와 안전하게 상호작용할 수 있게 해주는 표준화된 프로토콜입니다. 쉽게 말해, AI 모델에 손과 발을 달아주는 기술이라고 할 수 있죠.

오늘은 파이썬을 이용해 나만의 MCP 서버를 구축하는 방법을 단계별로 알아보겠습니다. 이 튜토리얼을 따라하면, 클로드와 같은 AI 비서가 여러분의 파일을 읽고, 데이터를 분석하며, API를 호출할 수 있게 됩니다.

MCP의 기본 개념 이해하기

MCP는 기본적으로 클라이언트-서버 아키텍처를 따릅니다:

MCP 호스트: 클로드 데스크톱 앱과 같은 AI 애플리케이션
MCP 클라이언트: 서버와 1:1 연결을 유지하는 프로토콜 클라이언트
MCP 서버: 특정 기능을 표준화된 방식으로 제공하는 경량 프로그램

MCP 서버는 AI 모델이 사용할 수 있는 도구(Tools), 리소스(Resources), 프롬프트(Prompts)라는 세 가지 유형의 기능을 제공합니다. 오늘 튜토리얼에서는 도구(Tools)를 중점적으로 다루겠습니다.

개발 환경 설정하기

MCP 서버 개발을 위해 필요한 환경을 설정해봅시다:

Python 3.9 이상 설치
프로젝트 디렉토리 생성 및 가상환경 설정
필요한 패키지 설치

먼저 터미널에서 다음 명령을 실행합니다:

# uv 설치 (최신 파이썬 패키지 관리자)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 프로젝트 초기화
uv init mcp_weather_server
cd mcp_weather_server

# 가상환경 생성 및 활성화
uv venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 필요한 패키지 설치
uv add "mcp[cli]" requests

첫 번째 MCP 서버 구축하기

이제 간단한 날씨 정보를 제공하는 MCP 서버를 만들어 보겠습니다. 이 서버는 두 가지 도구를 제공합니다:

get-forecast: 특정 지역의 날씨 예보를 가져옵니다.
get-alerts: 특정 지역의 기상 경보를 가져옵니다.

먼저 server.py 파일을 만들고 다음 코드를 입력합니다:

from mcp.server.fastmcp import FastMCP, tool
import requests
import json

# 서버 인스턴스 초기화
mcp = FastMCP("weather")
NWS_BASE_URL = "https://api.weather.gov"

@mcp.list_tools()
def list_tools():
    """MCP 클라이언트에 사용 가능한 도구 목록을 제공합니다."""
    return [
        {
            "name": "get-forecast",
            "description": "특정 위치의 날씨 예보를 가져옵니다.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "latitude": {"type": "number", "description": "위도"},
                    "longitude": {"type": "number", "description": "경도"}
                },
                "required": ["latitude", "longitude"]
            }
        },
        {
            "name": "get-alerts",
            "description": "특정 지역의 기상 경보를 가져옵니다.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "area": {"type": "string", "description": "지역 코드 (예: KR, US-CA)"}
                },
                "required": ["area"]
            }
        }
    ]

def get_points_metadata(lat, lon):
    """특정 위치의 메타데이터를 가져옵니다."""
    url = f"{NWS_BASE_URL}/points/{lat},{lon}"
    response = requests.get(url, headers={"Accept": "application/json"})
    return response.json()

def get_forecast_from_metadata(metadata):
    """메타데이터에서 예보 URL을 추출하여 예보를 가져옵니다."""
    forecast_url = metadata["properties"]["forecast"]
    response = requests.get(forecast_url, headers={"Accept": "application/json"})
    return response.json()

def format_forecast(forecast_data):
    """예보 데이터를 읽기 쉬운 형식으로 변환합니다."""
    periods = forecast_data["properties"]["periods"]
    formatted = []
    
    for period in periods[:5]:  # 처음 5개 기간만 사용
        formatted.append(f"{period['name']}: {period['temperature']}°{period['temperatureUnit']} - {period['shortForecast']}")
    
    return "\n".join(formatted)

@mcp.execute_tool()
def execute_tool(tool_name, tool_params):
    """도구 실행 핸들러"""
    if tool_name == "get-forecast":
        lat = tool_params["latitude"]
        lon = tool_params["longitude"]
        
        try:
            metadata = get_points_metadata(lat, lon)
            forecast_data = get_forecast_from_metadata(metadata)
            return format_forecast(forecast_data)
        except Exception as e:
            return f"날씨 예보를 가져오는데 실패했습니다: {str(e)}"
            
    elif tool_name == "get-alerts":
        area = tool_params["area"]
        
        try:
            url = f"{NWS_BASE_URL}/alerts/active?area={area}"
            response = requests.get(url, headers={"Accept": "application/json"})
            data = response.json()
            
            if len(data["features"]) == 0:
                return f"{area} 지역에 활성화된 경보가 없습니다."
            
            alerts = []
            for feature in data["features"][:5]:  # 처음 5개 경보만 사용
                props = feature["properties"]
                alerts.append(f"{props['headline']} - {props['severity']} ({props['effective']})")
            
            return "\n".join(alerts)
        except Exception as e:
            return f"기상 경보를 가져오는데 실패했습니다: {str(e)}"
    
    return f"알 수 없는 도구: {tool_name}"

if __name__ == "__main__":
    mcp.run()

서버 실행 및 클로드와 연결하기

서버 코드를 작성했으니 이제 실행하고 클로드 데스크톱과 연결해보겠습니다:

서버 실행: 터미널에서 다음 명령 실행
uv run server.py
클로드 데스크톱 설치: https://claude.ai/download에서 다운로드
클로드 설정 파일 수정: 다음 경로의 파일 수정설정 파일에 다음 내용 추가:※ "/절대/경로/"는 실제 프로젝트 폴더의 경로로 변경해주세요.
{ "mcpServers": { "weather": { "command": "uv", "args": [ "--directory", "/절대/경로/mcp_weather_server", "run", "server.py" ] } } }
# MacOS ~/Library/Application\ Support/Claude/claude_desktop_config.json # Windows %APPDATA%\Claude\claude_desktop_config.json
클로드 데스크톱 재시작: 앱을 완전히 종료하고 다시 실행

제대로 설정되었다면, 클로드 인터페이스에 도구 아이콘(망치 모양)이 나타나고 클릭하면 우리가 만든 도구들을 확인할 수 있습니다.

MCP 서버 개발 모범 사례

MCP 서버를 개발할 때 고려해야 할 몇 가지 모범 사례를 알아봅시다:

최소 권한 원칙: 서버가 필요한 최소한의 권한만 갖도록 설계하세요.
명확한 문서화: 도구에 대한 설명과 파라미터 설명을 상세히 제공하세요.
에러 처리: 발생 가능한 예외 상황을 고려하고 명확한 에러 메시지를 반환하세요.
비동기 지원: 시간이 오래 걸리는 작업은 비동기 함수(`async def`)로 구현하는 것이 좋습니다.
보안 고려: 민감한 데이터를 처리할 때는 적절한 인증 및 암호화 방식을 사용하세요.

확장 가능성: 더 많은 MCP 서버 아이디어

위에서 만든 기본 날씨 서버를 바탕으로 다양한 MCP 서버를 개발할 수 있습니다:

파일 시스템 도구: 로컬 파일 읽기/쓰기/검색
데이터베이스 연결: SQL 쿼리 실행 및 결과 반환
API 통합: 다양한 웹 API와 통합 (주식 정보, 뉴스, 번역 등)
코드 실행: 안전한 환경에서 코드 실행 및 결과 반환
이미지 처리: 이미지 분석, 생성 또는 편집 기능 제공

결론

MCP는 AI 모델의 새로운 능력을 열어주는 혁신적인 기술입니다. 이 튜토리얼을 통해 여러분은 기본적인 MCP 서버를 구축하고 클로드와 연결하는 방법을 배웠습니다.

앞으로 더 많은 도구와 기능을 추가하여 AI 모델의 능력을 확장해보세요. MCP는 단순한 텍스트 생성을 넘어, 실제 세계와 상호작용하는 AI 애플리케이션을 구축할 수 있는 기반을 제공합니다.

이 기술을 마스터하면 AI 개발의 최전선에 설 수 있을 것입니다. 행운을 빕니다!