AI Frontier10 days ago

Python으로 나만의 MCP 서버 만들기 — Claude와 연동하는 가장 쉬운 방법

클로드에게 내가 직접 짠 파이썬 코드를 쥐여주고 나만의 전용 도구로 활용할 수 있다면 얼마나 편할까요? 모델 컨텍스트 프로토콜(MCP)을 사용하면 내 컴퓨터에 있는 파일이나 스크립트를 클로드 데스크톱 앱에 아주 쉽게 연결할 수 있습니다. 복잡한 이론은 잠시 접어두고, 파이썬으로 5분 만에 작동하는 나만의 첫 번째 MCP 서버를 함께 만들어 보겠습니다.

MCP 서버, 굳이 왜 직접 만들어야 할까요?

클로드와 대화하다 보면 "이 녀석이 내 컴퓨터 파일도 직접 읽고, 내가 만든 자동화 코드도 알아서 실행해 주면 좋겠다"라는 생각이 절실해지곤 합니다. MCP 서버는 바로 이러한 상상을 현실로 연결해 주는 강력한 도구입니다.

거창한 시스템을 처음부터 새로 구축할 필요는 전혀 없습니다. 평소에 자주 쓰던 로컬 파일 정리 스크립트나 간단한 데이터 처리 로직을 파이썬 코드로 적어두기만 하면 됩니다. MCP 서버를 구동하는 순간, 내가 작성한 파이썬 함수가 그대로 클로드 데스크톱 앱에서 클릭 한 번으로 실행되는 전용 도구로 변신합니다.

이번 글에서는 초보자도 단 몇 줄의 코드만으로 이 마법 같은 연동을 끝낼 수 있도록 돕는 프리펙트(Prefect)의 FastMCP 라이브러리를 사용합니다. 복잡한 API 구조를 외우지 않아도 나만의 인공지능 비서를 만들 수 있는 가장 직관적인 방법을 함께 살펴보겠습니다.

FastMCP로 5분 만에 시작하는 초소형 서버 코드

과거에는 복잡한 공식 SDK 코드를 일일이 작성해야 해서 진입 장벽이 높았습니다. 하지만 최근에는 프리펙트가 관리하는 FastMCP 프레임워크 덕분에 개발이 놀라울 정도로 쉬워졌습니다. 이제는 까다로운 설정 없이 파이썬 함수 하나만으로 클로드에게 강력한 새 기능을 쥐여줄 수 있습니다.

동작 원리는 아주 단순합니다. 우리가 늘 쓰던 파이썬 함수 위에 데코레이터만 얹어주면 끝납니다. FastMCP가 파이썬의 타입 힌트와 주석으로 적은 설명글을 자동으로 분석해서, 클로드가 직접 해석하고 실행할 수 있는 도구 설계도로 알아서 변환해 주기 때문입니다.

두 숫자를 더해주는 초소형 도구 서버 코드를 통해 이 과정을 살펴보겠습니다. 다음은 FastMCP 4.x 버전을 기준으로 작성한 코드입니다.

python

from fastmcp import FastMCP

# MathServer라는 이름으로 MCP 서버를 만듭니다
mcp = FastMCP("MathServer")

@mcp.tool()
def add_numbers(a: int, b: int) -> int:
    """두 숫자를 더합니다.

    Args:
        a: 첫 번째 숫자
        b: 두 번째 숫자
    """
    return a + b

코드를 보면 입력 인수 옆에 정수를 뜻하는 타입이 지정되어 있고, 아래에 친절한 설명글이 적혀 있습니다. FastMCP는 이 정보를 바탕으로 클로드에게 "이 도구를 쓰려면 숫자 두 개를 보내야 해"라고 적힌 API 설명서를 실시간으로 만들어 전달합니다.

초보자가 가장 많이 하는 실수: print()를 쓰면 안 된다?

MCP 서버를 직접 만들다 보면 왜 잘 작동하던 코드가 클로드 데스크톱에만 연결하면 먹통이 되는지 당황할 때가 많습니다. 범인은 바로 우리가 디버깅을 위해 습관적으로 사용하는 print() 함수입니다.

로컬 MCP 서버는 기본적으로 표준 입출력(STDIO) 방식을 통해 클로드와 통신합니다. 클로드는 서버가 표준 출력으로 보내는 깔끔하게 정돈된 데이터만 해석하려고 대기하고 있습니다. 그런데 여기에 일반적인 print()가 무심코 섞여 들어오면 메시지 규격이 오염되면서 연결이 즉시 끊어져 버립니다.

따라서 개발 중에 진행 상황을 확인하거나 오류를 추적하고 싶을 때는 반드시 표준 에러(stderr)를 사용해야 합니다. 파이썬 표준 라이브러리를 기준으로 올바른 로깅 방식과 잘못된 방식을 간단히 비교해 보겠습니다.

python

import sys
import logging

# ❌ 잘못된 방법: 표준 출력을 오염시켜 클로드와의 연결을 즉시 끊어지게 만듭니다.
print("데이터를 가져오는 중...")

# ✅ 올바른 방법: 표준 에러로 우회 출력하여 통신을 방해하지 않습니다.
print("데이터를 가져오는 중...", file=sys.stderr)

# ✅ 권장하는 방법: 파이썬의 로깅 모듈은 기본적으로 표준 에러로 안전하게 출력됩니다.
logging.info("데이터를 가져오는 중...")

FastMCP 환경에서는 도구 함수 안에 Context 객체를 전달받아 클로드 앱 화면에 직접 로그를 뿌려주는 더 고도화된 기능도 지원합니다. 하지만 복잡한 기능 이전에 표준 출력의 흐름을 방해하지 않는 기본 규칙만 지켜도 초보자가 겪는 MCP 에러의 절반 이상을 예방할 수 있습니다.

Claude Desktop에 한 번에 연결하고 테스트하기

열심히 만든 서버를 이제 실제 클로드 데스크톱 앱에 연동할 차례입니다. 연동하는 방법은 자동 설치 명령어를 쓰거나 설정 파일을 직접 수정하는 것, 이렇게 두 가지가 있습니다.

가장 빠르고 쉬운 방법은 FastMCP가 제공하는 자동 설치 명령어를 사용하는 것입니다. 터미널에서 다음 명령어를 실행하면 자동으로 등록됩니다.

bash

uv run fastmcp install server.py --name "MyServer"

이 명령어를 입력하면 FastMCP가 클로드 데스크톱 설정 파일에 우리 서버를 알아서 등록해 줍니다. 만약 수동으로 직접 등록하고 싶다면 설정 파일을 직접 편집할 수도 있습니다. 설정 파일인 claude_desktop_config.json은 사용하는 운영체제에 따라 아래 경로에 들어있습니다.

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
윈도우: %APPDATA%\Claude\claude_desktop_config.json

클로드 데스크톱은 터미널 환경과 독립적으로 실행되기 때문에, 설정 파일을 직접 고칠 때는 파이썬 실행 파일과 서버 스크립트를 반드시 절대 경로로 작성해야 에러가 나지 않습니다. 아래 예시처럼 작성하면 됩니다.

json

{
  "mcpServers": {
    "my-custom-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "/absolute/path/to/server.py"
      ]
    }
  }
}

앱에 직접 연동하기 전에 도구가 올바르게 작동하는지 시각적으로 테스트하고 싶다면 mcp dev 명령어를 활용해 보세요. 터미널에 mcp dev server.py를 실행하면 웹 브라우저에서 서버 상태를 편리하게 확인할 수 있는 MCP 인스펙터 창이 열립니다.

다만 한 가지 보안 주의사항이 있습니다. 최근 MCP 인스펙터 도구에서 발견된 보안 취약점(CVE-2025-49596) 때문에 최신 버전에서는 토큰 인증이 필수로 강화되었습니다. 따라서 로컬에서 안전하게 테스트하려면 터미널에 출력된 링크 뒤의 보안 토큰(?MCP_PROXY_AUTH_TOKEN=...)을 반드시 포함해서 접속하거나, 로컬 단독 테스트 환경인 경우 DANGEROUSLY_OMIT_AUTH=true 환경 변수를 일시적으로 지정하고 실행해야 원활한 접속이 가능합니다.

나만의 에이전트 생태계 만들기

파이썬 함수 몇 줄로 클로드에 커스텀 도구를 연결하는 첫걸음을 무사히 뗐습니다. 이제 실시간 날씨 정보 가져오기나 로컬 파일 요약처럼, 내 일상에 진짜 필요한 실용적인 기능들을 하나씩 추가해 보세요. 내 손으로 직접 도구를 쥐여주고 실험하는 나만의 인공지능 에이전트 만들기, 생각보다 어렵지 않습니다.