MCP 서버 총정리 | 사용법 및 구축 방법 까지 10분 만에 완성하는 초보자 가이드

MCP 서버를 구축하고 설정하는 것은 처음에는 복잡해 보일 수 있지만, 올바른 가이드와 도구를 사용하면 누구나 쉽게 시작할 수 있습니다. 이 글에서는 MCP 서버의 기본 개념부터 설치, 설정, 확장 방법까지 단계별로 설명합니다. 초보자도 따라 할 수 있도록 간단하고 명확하게 작성했으니, 끝까지 읽어보세요!

MCP 서버란 무엇인가?

MCP 서버는 **MCP(모델 컨텍스트 프로토콜)**의 일부로, 대규모 언어 모델(LLM)이 외부 데이터 소스와 도구에 접근할 수 있도록 돕는 프로그램입니다. 이는 AI 시스템과 외부 시스템 간의 상호작용을 표준화하여, 데이터를 효율적으로 교환하고 작업을 수행할 수 있게 합니다.

MCP 서버의 역할

MCP 서버는 LLM이 외부 데이터와 상호작용할 수 있도록 지원합니다. 예를 들어, 파일 읽기, API 호출, 데이터베이스 접근 등을 가능하게 합니다. 이를 통해 LLM의 기능을 확장하고, 사용자 경험을 개선할 수 있습니다.

MCP 서버를 사용하는 이유

MCP 서버를 사용하면 다음과 같은 이점이 있습니다:

데이터 접근성 향상: LLM이 실시간 데이터에 접근 가능
기능 확장: 기존 AI 모델에 새로운 도구와 기능 추가
표준화된 통합: 다양한 LLM과 호환 가능

MCP 서버의 주요 기능

MCP 서버는 크게 세 가지 기능을 제공합니다:

MCP 서버 세가지 기능

리소스(Resources): 파일, 데이터베이스, API 응답 등 읽기 전용 데이터 제공
도구(Tools): 사용자 요청에 따라 실행 가능한 함수 제공
프롬프트(Prompts): 특정 작업을 수행하기 위한 템플릿 제공

MCP 서버 구축을 위한 사전 준비

MCP 서버를 구축하기 전에 필요한 소프트웨어와 하드웨어를 준비해야 합니다. 아래는 필수 준비 사항입니다.

필요한 소프트웨어 및 하드웨어 요구사항

운영 체제: Windows, macOS, Linux
Python 3.10 이상: MCP SDK 설치를 위해 필요
Claude Desktop: MCP 서버 테스트 및 통합 (macOS, Windows 지원)

MCP 프레임워크 다운로드 및 설치 - Python 버전

MCP 프레임워크는 MCP 서버의 핵심입니다.

Python:

# uv 설치 (권장)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 프로젝트 생성 및 설정
uv init my-first-mcp-server
cd my-first-mcp-server
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx

개발 환경 설정

VS Code나 Cursor AI 와 같은 IDE를 사용하면 개발 생산성을 높일 수 있습니다.

MCP 서버 구축 단계별 가이드

이제 MCP 서버를 구축하는 구체적인 단계를 살펴보겠습니다.

1. 기본 MCP 서버 구현

Python을 이용한 기본 서버 구현

프로젝트 생성 및 설정 방법

# 프로젝트를 위한 새 디렉토리 생성
uv init weather
cd weather

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

# 의존성 설치
uv add "mcp[cli]" httpx

# 서버 파일 생성
touch weather.py

패키지 가져오기 및 인스턴스 설정

weather.py 파일 상단에 다음 코드를 추가합니다:

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# FastMCP 서버 초기화
mcp = FastMCP("weather")

# 상수
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

FastMCP 클래스는 Python 타입 힌트와 독스트링을 활용하여 도구 정의를 자동으로 생성하므로 MCP 도구를 쉽게 만들고 관리할 수 있습니다.

헬퍼 함수

다음으로 National Weather Service API에서 데이터를 쿼리하고 형식을 지정하는 헬퍼 함수를 추가합니다:

async def make_nws_request(url: str) -> dict[str, Any] | None:
    """NWS API에 적절한 오류 처리로 요청합니다."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """알림 기능을 읽기 쉬운 문자열로 형식화합니다."""
    props = feature["properties"]
    return f"""
이벤트: {props.get('event', '알 수 없음')}
지역: {props.get('areaDesc', '알 수 없음')}
심각도: {props.get('severity', '알 수 없음')}
설명: {props.get('description', '설명 없음')}
지침: {props.get('instruction', '특별한 지침 없음')}
"""

도구 실행 구현

도구 실행 핸들러는 각 도구의 로직을 실제로 실행하는 역할을 합니다:

@mcp.tool()
async def get_alerts(state: str) -> str:
    """미국 주의 기상 알림을 가져옵니다.

    Args:
        state: 두 글자 미국 주 코드 (예: CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "알림을 가져올 수 없거나 알림이 없습니다."

    if not data["features"]:
        return "이 주에 대한 활성 알림이 없습니다."

    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """위치에 대한 기상 예보를 가져옵니다.

    Args:
        latitude: 위치의 위도
        longitude: 위치의 경도
    """
    # 먼저 예보 그리드 엔드포인트 가져오기
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "이 위치에 대한 예보 데이터를 가져올 수 없습니다."

    # 포인트 응답에서 예보 URL 가져오기
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "상세 예보를 가져올 수 없습니다."

    # 기간을 읽기 쉬운 예보로 포맷팅
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # 다음 5개 기간만 표시
        forecast = f"""
{period['name']}:
온도: {period['temperature']}°{period['temperatureUnit']}
바람: {period['windSpeed']} {period['windDirection']}
예보: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

서버 실행

마지막으로 서버를 초기화하고 실행합니다:

if __name__ == "__main__":
    # 서버 초기화 및 실행
    mcp.run(transport='stdio')

이제 서버가 완성되었습니다! uv run weather.py를 실행하여 모든 것이 제대로 작동하는지 확인하세요.

uv run weather.py

이제 기존 MCP 호스트(예: Claude for Desktop)에서 서버를 테스트할 수 있습니다.

2. 리소스(Resources) 추가하기

리소스는 LLM이 읽을 수 있는 데이터를 제공합니다. 다음은 간단한 리소스 구현 예제입니다:

Python 리소스 예제

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("resource-server")

@mcp.resource_root()
async def info(request):
    return {
        "uri": "info://about",
        "name": "서비스 정보",
        "description": "우리 서비스에 대한 기본 정보"
    }

@mcp.resource("info://about")
async def about_info():
    return "이 서비스는 MCP 서버 예제입니다."

if __name__ == "__main__":
    mcp.run(transport='stdio')

3. 도구(Tools) 구현하기

도구는 LLM이 사용자 요청에 따라 실행할 수 있는 함수입니다. 다음은 간단한 날씨 정보 제공 도구 예제입니다:

Python 도구 예제

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("weather-server")

NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

async def make_nws_request(url: str):
    """NWS API에 요청을 보내는 헬퍼 함수"""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """주어진 위치의 날씨 예보를 가져옵니다.
    
    Args:
        latitude: 위치의 위도
        longitude: 위치의 경도
    """
    # 예보 그리드 엔드포인트 가져오기
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)
    
    if not points_data:
        return "이 위치의 예보 데이터를 가져올 수 없습니다."
    
    # 예보 URL 가져오기
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)
    
    if not forecast_data:
        return "상세 예보를 가져올 수 없습니다."
    
    # 기간을 읽기 쉬운 예보로 포맷팅
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # 다음 5개 기간만 표시
        forecast = f"""
{period['name']}:
온도: {period['temperature']}°{period['temperatureUnit']}
바람: {period['windSpeed']} {period['windDirection']}
예보: {period['detailedForecast']}
"""
        forecasts.append(forecast)
    
    return "\n---\n".join(forecasts)

if __name__ == "__main__":
    mcp.run(transport='stdio')

4. 프롬프트(Prompts) 구현하기

프롬프트는 LLM에게 특정 작업 수행을 위한 템플릿을 제공합니다:

Python 프롬프트 예제

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("prompts-server")

@mcp.prompt("이메일 작성")
def email_prompt():
    return """
    다음 정보로 이메일을 작성해주세요:

    주제: {{subject}}
    수신자: {{recipient}}
    어조: {{tone}}
    주요 요점:
    {% for point in key_points %}
    - {{point}}
    {% endfor %}
    """

@mcp.prompt("블로그 글 작성")
def blog_prompt():
    return """
    다음 주제로 블로그 글을 작성해주세요: {{topic}}
    
    키워드: {{keywords}}
    어조: {{tone}}
    길이: {{length}} 단어
    대상 독자: {{audience}}
    """

if __name__ == "__main__":
    mcp.run(transport='stdio')

Claude Desktop과 MCP 서버 연결하기

개발한 MCP 서버를 Claude Desktop과 연결하는 방법은 다음과 같습니다:

Claude Desktop 설정 방법

Claude Desktop 다운로드 및 설치
- macOS 또는 Windows용 Claude Desktop을 다운로드하여 설치합니다 (Linux는 아직 지원되지 않음)
- 이미 설치되어 있다면 Claude 메뉴에서 "Check for Updates..."를 선택하여 최신 버전으로 업데이트
Claude Desktop 구성 파일 설정
- Claude 메뉴에서 "Settings..." 선택 (앱 내의 Claude Account Settings가 아님)

Claude Desktop 설정 메뉴

왼쪽 메뉴에서 "Developer" 선택 후 "Edit Config(설정 편집)" 클릭

Claude Desktop MCP 설정 화면

구성 파일 위치:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

구성 파일에 MCP 서버 정보 추가:

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "절대경로/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

Claude Desktop 재시작

연결 확인 및 테스트

Claude Desktop 시작
채팅 인터페이스에서 MCP 도구 아이콘(망치 아이콘) 클릭
서버 목록에서 연결할 MCP 서버 선택
리소스, 도구 또는 프롬프트를 사용하여 테스트

예시 명령:

"오늘 서울의 날씨는 어때?"
"내일 뉴욕의 날씨 예보를 보여줘."

MCP 서버 디버깅 및 문제 해결

MCP 서버 개발 시 발생할 수 있는 문제를 해결하는 방법입니다.

일반적인 문제 및 해결 방법

서버 연결 실패
- 파일 경로가 올바른지 확인
- 실행 권한 확인 (chmod +x)
- 구성 파일의 JSON 형식 확인
도구 실행 오류
- 매개변수 타입 확인
- 비동기 함수 처리 확인
- 에러 처리 추가
리소스 로드 실패
- URI 형식 확인
- MIME 타입 설정 확인

MCP 서버 확장 및 최적화

MCP 서버를 더 강력하게 만들기 위한 확장 및 최적화 방법입니다.

데이터베이스 연결

MCP 서버에 데이터베이스를 연결하여 동적 데이터를 제공할 수 있습니다:

import sqlite3
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("db-server")

def get_db_connection():
    conn = sqlite3.connect('database.db')
    conn.row_factory = sqlite3.Row
    return conn

@mcp.tool()
async def search_products(query: str) -> str:
    """제품을 검색합니다.
    
    Args:
        query: 검색어
    """
    conn = get_db_connection()
    products = conn.execute(
        'SELECT * FROM products WHERE name LIKE ? LIMIT 10', 
        (f'%{query}%',)
    ).fetchall()
    conn.close()
    
    if not products:
        return "검색 결과가 없습니다."
    
    results = []
    for product in products:
        results.append(f"ID: {product['id']}, 이름: {product['name']}, 가격: {product['price']}원")
    
    return "\n".join(results)

API 통합

외부 API와 통합하여 MCP 서버의 기능을 확장할 수 있습니다:

import httpx
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("api-server")

@mcp.tool()
async def translate_text(text: str, target_lang: str) -> str:
    """텍스트를 번역합니다.
    
    Args:
        text: 번역할 텍스트
        target_lang: 대상 언어 코드 (예: 'en', 'ja', 'zh')
    """
    API_URL = "https://api.example-translator.com/translate"
    API_KEY = "your-api-key"  # 실제 환경에서는 환경 변수 사용 권장
    
    async with httpx.AsyncClient() as client:
        response = await client.post(
            API_URL,
            json={"text": text, "target": target_lang},
            headers={"Authorization": f"Bearer {API_KEY}"}
        )
        
        if response.status_code != 200:
            return f"번역 오류: {response.text}"
        
        data = response.json()
        return data["translated_text"]

성능 최적화 팁

MCP 서버의 성능을 개선하기 위한 팁:

비동기 처리 활용
- Python에서는 async/await 사용
- JavaScript에서는 Promise 활용
캐싱 구현
- 자주 요청되는 데이터 캐싱
- Redis와 같은 인메모리 캐시 활용
리소스 효율적 관리
- 커넥션 풀 사용
- 메모리 누수 방지
에러 처리 강화
- 예외 상황 대비
- 적절한 오류 메시지 제공

실제 사례: 날씨 정보 제공 MCP 서버

실제 작동하는 날씨 정보 제공 MCP 서버의 전체 코드입니다. 이 예제를 통해 MCP 서버의 기능을 종합적으로 이해할 수 있습니다.

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# FastMCP 서버 초기화
mcp = FastMCP("weather")

# 상수
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

# 헬퍼 함수
async def make_nws_request(url: str) -> dict[str, Any] | None:
    """NWS API에 요청을 보내는 함수"""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """경보 정보를 가독성 있게 포맷팅"""
    props = feature["properties"]
    return f"""
이벤트: {props.get('event', '알 수 없음')}
지역: {props.get('areaDesc', '알 수 없음')}
심각도: {props.get('severity', '알 수 없음')}
설명: {props.get('description', '설명 없음')}
지침: {props.get('instruction', '특별한 지침 없음')}
"""

# 도구 구현
@mcp.tool()
async def get_alerts(state: str) -> str:
    """미국 주별 날씨 경보를 가져옵니다.
    
    Args:
        state: 미국 주 코드 (예: CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)
    
    if not data or "features" not in data:
        return "경보를 가져올 수 없거나 경보가 없습니다."
    
    if not data["features"]:
        return "이 주에 활성화된 경보가 없습니다."
    
    alerts = [format_alert(feature) for feature in data["features"]]
    return "\n---\n".join(alerts)

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """위치 기반 날씨 예보를 가져옵니다.
    
    Args:
        latitude: 위치의 위도
        longitude: 위치의 경도
    """
    # 예보 그리드 엔드포인트 가져오기
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)
    
    if not points_data:
        return "이 위치의 예보 데이터를 가져올 수 없습니다."
    
    # 예보 URL 가져오기
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)
    
    if not forecast_data:
        return "상세 예보를 가져올 수 없습니다."
    
    # 기간을 읽기 쉬운 예보로 포맷팅
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # 다음 5개 기간만 표시
        forecast = f"""
{period['name']}:
온도: {period['temperature']}°{period['temperatureUnit']}
바람: {period['windSpeed']} {period['windDirection']}
예보: {period['detailedForecast']}
"""
        forecasts.append(forecast)
    
    return "\n---\n".join(forecasts)

# 서버 실행
if __name__ == "__main__":
    mcp.run(transport='stdio')

결론

MCP 서버는 AI 모델과 외부 시스템을 연결하는 강력한 도구입니다. 이 가이드에서는 MCP 서버의 기본 개념부터 구축, 설정, 확장까지 단계별로 알아보았습니다.

이제 여러분은 다음을 할 수 있게 되었습니다:

MCP 서버의 핵심 개념 이해
기본 MCP 서버 구축
리소스, 도구, 프롬프트 구현
Claude Desktop과 연결 설정
문제 해결 및 디버깅
MCP 서버 확장 및 최적화

MCP 기술은 계속 발전하고 있으며, 이를 통해 AI 모델의 가능성이 더욱 확장될 것입니다. 이 가이드가 여러분의 MCP 서버 구축 여정에 도움이 되길 바랍니다!

MCP 서버란 무엇인가?​

MCP 서버의 역할​

MCP 서버를 사용하는 이유​

MCP 서버의 주요 기능​

MCP 서버 구축을 위한 사전 준비​

필요한 소프트웨어 및 하드웨어 요구사항​

MCP 프레임워크 다운로드 및 설치 - Python 버전​

개발 환경 설정​

MCP 서버 구축 단계별 가이드​

1. 기본 MCP 서버 구현​

Python을 이용한 기본 서버 구현​

도구 실행 구현​

서버 실행​

2. 리소스(Resources) 추가하기​

Python 리소스 예제​

3. 도구(Tools) 구현하기​

Python 도구 예제​

4. 프롬프트(Prompts) 구현하기​

Python 프롬프트 예제​

Claude Desktop과 MCP 서버 연결하기​

Claude Desktop 설정 방법​

연결 확인 및 테스트​

MCP 서버 디버깅 및 문제 해결​

일반적인 문제 및 해결 방법​

MCP 서버 확장 및 최적화​

데이터베이스 연결​

API 통합​

성능 최적화 팁​

실제 사례: 날씨 정보 제공 MCP 서버​

결론​

참고 자료​