🛠️ 30분 만에 끝내는 나만의 MCP 서버 구축하기 (Python & SDK 가이드)

자료 기본정보

- 설명

안녕하세요! 개발자 여러분. 최근 앤스로픽(Anthropic)이 발표한 **Model Context Protocol(MCP)**은 AI 모델이 외부 데이터나 도구와 상호작용하는 방식을 완전히 바꾸고 있습니다. 이제 개발자는 단순히 프롬프트를 짜는 것을 넘어, AI가 우리 회사의 DB를 읽거나 특정 API를 호출하게 만드는 '커넥터'를 직접 설계해야 하는 시대가 왔습니다. 오늘은 가장 생산성이 높은 Python SDK를 활용해 단 30분 만에 나만의 MCP 서버를 구축하는 실전 과정을 공유하겠습니다.

1. MCP 서버란 무엇인가? (Architecture Overview)

MCP 서버는 AI 모델(클라이언트)과 데이터 소스 사이의 중계자 역할을 합니다. 표준화된 JSON-RPC 기반의 규격을 사용하여, 클로드가 "이 데이터 좀 가져와줘"라고 요청하면 서버가 이를 해석해 실제 데이터를 전달하는 구조입니다.

이 구조의 핵심은 상호운용성입니다. 한 번 만든 MCP 서버는 클로드 데스크톱뿐만 아니라 MCP 표준을 지원하는 모든 IDE나 서비스에서 즉시 사용할 수 있습니다.

2. 개발 환경 준비

본격적인 코딩에 앞서 필요한 패키지를 설치해야 합니다. Python 3.10 이상의 환경을 권장합니다.

Bash

# MCP SDK 설치
pip install mcp

우리는 오늘 **'현재 시스템의 리소스 상태를 알려주는 서버'**를 예제로 만들어 보겠습니다. AI가 내 컴퓨터의 CPU와 메모리 상태를 실시간으로 파악해 최적화 제안을 할 수 있게 만드는 것이 목표입니다.

3. 단계별 서버 구현

Step 1: 서버 인스턴스 생성

가장 먼저 MCP 서버의 본체를 선언합니다.

Python

from mcp.server.fastmcp import FastMCP

# 'SystemMonitor'라는 이름의 MCP 서버 생성
mcp = FastMCP("SystemMonitor")

Step 2: 도구(Tool) 등록하기

MCP의 핵심은 AI가 호출할 수 있는 Tool을 정의하는 것입니다. @mcp.tool() 데코레이터를 사용하면 파이썬 함수가 즉시 AI의 도구가 됩니다.

Python

import psutil

@mcp.tool()
def get_system_stats() -> str:
    """현재 컴퓨터의 CPU와 메모리 사용량을 반환합니다."""
    cpu = psutil.cpu_percent(interval=1)
    memory = psutil.virtual_memory().percent
    return f"현재 CPU 사용률은 {cpu}%이며, 메모리 사용률은 {memory}%입니다."

Tip: 함수의 Docstring(주석)은 AI가 이 도구를 언제 사용해야 할지 판단하는 근거가 되므로 매우 상세히 적어야 합니다.

Step 3: 리소스(Resource) 정의하기

도구가 '행동'이라면, 리소스는 '데이터'입니다. 정적인 텍스트나 로그 파일 등을 AI에게 노출할 때 사용합니다.

Python

@mcp.resource("system://info")
def system_info() -> str:
    return "이 서버는 MCP SDK를 통해 구축된 시스템 모니터링 전용 노드입니다."

4. 서버 실행 및 Claude Desktop 연동

이제 우리가 만든 서버를 클로드에게 인식시켜야 합니다.

1. 로컬 경로 확인: 작성한 파이썬 파일의 절대 경로를 복사합니다. (예: C:/dev/mcp_server.py)

2. 설정 파일 수정: Claude Desktop의 설정 파일(claude_desktop_config.json)을 엽니다.

JSON

{
  "mcpServers": {
    "my-monitor": {
      "command": "python",
      "args": ["C:/dev/mcp_server.py"]
    }
  }
}

3. 확인: 클로드를 재시작하고 "내 컴퓨터 시스템 상태 어때?"라고 물어보세요. 클로드가 get_system_stats 도구를 스스로 실행하여 답변을 내놓는다면 성공입니다.

5. 실무 응용: 내부 DB 및 API 연결

위 예제를 확장하면 무궁무진한 활용이 가능합니다.

• Internal DB 연결: SQLAlchemy 등을 활용해 특정 쿼리 결과를 반환하는 도구를 만들면, AI가 사내 지표를 실시간 분석할 수 있습니다.

• API 연동: 사내 Jira나 Slack API를 연동하여 "어제 등록된 버그 티켓들 요약해서 보고해줘" 같은 요청을 처리할 수 있습니다.

6. 개발자들을 위한 꿀팁

1. 에러 핸들링: MCP 서버 내부에서 발생하는 예외는 반드시 텍스트로 래핑해서 반환하세요. AI가 에러 메시지를 보고 스스로 수정을 시도할 수 있습니다.

2. 보안: AI에게 모든 권한을 주기보다, 필요한 읽기 전용(ReadOnly) 쿼리만 노출하는 것이 안전합니다.

3. 성능: 대용량 데이터를 한 번에 보내기보다 필요한 부분만 필터링해서 전달하도록 도구 인자(Arguments)를 설계하세요.

✅ 마무리하며

MCP는 AI와 데이터 사이의 벽을 허무는 혁명적인 도구입니다. 이제 단순한 프롬프트 엔지니어를 넘어, AI의 감각기관과 팔다리가 되어줄 MCP 서버 엔지니어의 역할이 중요해질 것입니다. 오늘 알려드린 Python SDK를 활용해 여러분만의 독창적인 AI 에이전트 생태계를 구축해 보시기 바랍니다.

도움이 되셨다면 공감과 댓글 부탁드리며, 구현 중 막히는 부분은 언제든 질문해 주세요!

주요 키워드 개발자블로그, SDK, Python, TypeScript, 오픈소스, MCP, Anthropic, AI에이전트, JSON-RPC, 서버구축