Molayo

© 2026 Molayo

Dev.to헤드라인2026. 06. 19. 18:04

Python MCP 서버 처음부터 구축하기 - 실전 GitHub API 가이드

요약

Anthropic의 Model Context Protocol(MCP)을 사용하여 Python 기반의 GitHub API 서버를 처음부터 구축하는 실전 가이드입니다. 도구, 리소스, 프롬프트 정의부터 MCP Inspector를 활용한 테스트 및 Claude Desktop 연결 방법까지 상세히 다룹니다.

핵심 포인트

  • MCP의 핵심 프리미티브인 도구(Tools), 리소스(Resources), 프롬프트(Prompts) 이해
  • FastMCP를 활용한 간결한 Python MCP 서버 구현 방법
  • MCP Inspector를 이용한 서버 디버깅 및 테스트 프로세스
  • GitHub API를 연동한 실전적인 외부 데이터 호출 예제 제공

Model Context Protocol (MCP)은 2년도 채 되지 않아 Anthropic의 틈새 프로젝트에서 산업 표준 인프라로 성장했습니다. 월간 SDK 다운로드 9,700만 회를 기록하며 Linux Foundation 산하로 영구적으로 편입되었습니다. 이제 모든 주요 AI 코딩 도구가 MCP를 기본적으로 지원하지만, 대부분의 튜토리얼은 설치할 이미 구축된 서버 목록을 나열하거나 실제적인 구축 없이 사양(spec)만 읊고 있습니다.

이 가이드는 도구(tools), 리소스(resources), 프롬프트(prompts) 정의부터 MCP Inspector를 이용한 테스트, 그리고 Claude Desktop 또는 Claude Code에 연결하는 과정까지 Python MCP 서버를 처음부터 작성하는 방법을 안내합니다. 작동 예제는 GitHub API를 대상으로 하며, 이는 AI 어시스턴트 내에서 실시간 외부 데이터가 필요한 모든 프로젝트로 확장할 수 있는 실용적인 시작점입니다.

사전 요구 사항: Python 3.10 이상, uv 또는 pip, 그리고 Claude Desktop 또는 Claude Code가 설치되어 있어야 합니다.

MCP 서버가 실제로 하는 일

MCP는 AI 클라이언트가 외부 서비스를 호출할 수 있는 표준화된 방법을 제공하는 JSON-RPC 프로토콜입니다. Claude, Cursor 또는 기타 준수하는 도구와 같은 클라이언트가 요청을 보내면, 서버가 어떤 언어로 작성되었는지에 관계없이 이를 처리합니다.

모든 MCP 서버는 세 가지 핵심 프리미티브(primitives)를 노출합니다. 도구(Tools)는 AI가 동작을 수행하거나 데이터를 가져오기 위해 호출할 수 있는 실행 가능한 함수입니다. 리소스(Resources)는 AI가 가져올 수 있는 읽기 전용 데이터 엔드포인트로, 파일이나 데이터베이스 레코드와 유사합니다. 프롬프트(Prompts)는 서버에 저장되어 이름으로 참조되는 재사용 가능한 지침 템플릿이며, 팀 전체의 워크플로우를 표준화하는 데 유용합니다.

전송(transport)을 위해 이 가이드는 stdio를 사용합니다. 즉, 서버가 서브프로세스로 실행되며 stdin/stdout을 통해 통신합니다. 이는 Claude Desktop 및 Claude Code에서 즉시 작동합니다. 프로덕션 또는 원격 배포의 경우, Streamable HTTP가 대안이 될 수 있습니다.

프로젝트 설정하기

새 디렉토리를 생성하고 개발 서버 및 인스펙터 런처가 포함된 [cli] 추가 기능이 있는 MCP SDK를 설치합니다:

mkdir github-mcp-server
cd github-mcp-server
uv init .
...

만약 pip를 선호한다면, 대신 pip install "mcp[cli]" httpx를 실행하세요. 프로젝트에는 딱 세 개의 파일이 필요합니다: server.py, pyproject.toml (uv를 사용하는 경우), 그리고 GitHub 토큰을 위한 선택 사항인 .env 파일입니다.

10줄로 만드는 최소 기능 도구 (Minimal Tool)

전체 서버를 구축하기 전에, 가능한 가장 단순한 작동 예제로 시작해 보세요. 이를 통해 실제 로직을 추가하기 전, SDK가 올바르게 연결되었는지 확인할 수 있습니다:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-mcp")
...

uv run mcp dev server.py를 실행하여 http://localhost:5173에서 MCP Inspector를 실행하세요. Tools 탭으로 이동하여 아무 이름이나 넣어 greet를 호출하고 응답을 확인합니다. 여기서 중요한 세 가지가 있습니다: FastMCP가 모든 JSON-RPC 배관(plumbing) 작업을 처리하고, @mcp.tool() 데코레이터가 타입 힌트(type hints)로부터 스키마(schema)를 자동 생성하며, 독스트링(docstring)은 AI가 이 도구를 호출할지 결정하기 위해 읽는 내용이므로 명확하게 작성해야 합니다.

GitHub 도구 서버 구축하기

이제 그 최소 기능 예제를 실제 서버로 교체해 보겠습니다. 이 버전은 두 가지 도구를 노출합니다: 하나는 저장소 메타데이터를 가져오는 도구이고, 다른 하나는 열려 있는 이슈(open issues)를 나열하는 도구이며, 두 도구 모두 httpx를 통한 실시간 GitHub API 호출을 기반으로 합니다.

import os, logging, sys, httpx
from pydantic import BaseModel
from mcp.server.fastmcp import FastMCP
...

의도적인 몇 가지 설계 선택 사항을 주목할 가치가 있습니다. 도구에서 Pydantic 모델을 반환하면 AI가 필드별로 참조할 수 있는 타입이 지정된 구조화된 응답을 받게 되는데, 이는 서식화된 문자열을 파싱하는 것보다 훨씬 더 신뢰할 수 있습니다. 문자열을 반환하는 도구의 경우, 예외(exception)를 포착하여 에러 메시지를 반환하는 것이 예외를 그대로 전파하는 것보다 안전합니다. stdio 환경에서 처리되지 않은 예외가 발생하면 전체 연결이 끊길 수 있기 때문입니다. limit와 같은 숫자 입력값은 항상 제한(clamp)을 두어야 합니다. AI가 가끔 0, 100 또는 문자열을 보낼 수 있기 때문입니다.

리소스(Resources) 및 프롬프트(Prompts) 추가하기

리소스(Resources)를 사용하면 AI가 수동적으로 데이터를 읽을 수 있습니다. 여기 GitHub 토큰이 설정되었는지 보고하는 리소스와, 저장소의 README를 가져오는 동적 리소스가 있습니다:

@mcp.resource("config://github-tools/status")
def server_status() -> str:
    """서버에 GitHub 토큰이 설정되어 있는지 보고합니다."""
...

프롬프트 (Prompts)는 모든 MCP 클라이언트가 이름으로 호출할 수 있는 지침 템플릿 (instruction templates)으로 저장됩니다. 이 프롬프트는 우리가 정의한 GitHub 도구들을 중심으로 코드 리뷰 요청을 구성합니다:

@mcp.prompt()
def review_pull_request(owner: str, repo: str, pr_number: int) -> str:
    """GitHub 풀 리퀘스트 (pull request) 리뷰를 위한 프롬프트 템플릿."""
...

MCP Inspector를 통한 테스트

서버를 검증하는 가장 빠른 방법은 내장된 인스펙터 (inspector)를 사용하는 것입니다. Claude가 필요하지 않습니다. uv run mcp dev server.py를 실행하고 http://localhost:5173을 여세요.

연결하기 전에 환경 변수 (Environment Variables) 섹션에서 GITHUB_TOKEN을 설정하세요. 그런 다음 도구 (Tools) 탭에서 도구를 테스트하고, 리소스 (Resources) 탭에서 리소스를 확인하며, 프롬프트 (Prompts) 탭에 프롬프트가 나타나는지 확인하세요. 만약 무언가 실패한다면, 로그 (Logs) 패널에 원시 JSON-RPC 교환 내용이 표시되며, 이는 문제를 정확히 찾아낼 수 있는 가장 직접적인 방법입니다.

Claude Desktop 연결하기

Claude Desktop 설정 파일을 여세요. macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json에, Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json에 있습니다. mcpServers 아래에 서버를 추가하세요:

{
  "mcpServers": {
    "github-tools": {
...

단순한 python 명령 대신 uv run을 사용하세요. Claude Desktop은 사용자의 PATH 없이 자체 셸 환경을 생성하므로, 단순한 python 명령은 종종 실패합니다. 저장 후 Claude Desktop을 완전히 종료했다가 다시 시작하세요. 입력창에 플러그 아이콘이 나타나면 서버가 연결되었음을 확인해 줍니다.

Claude Code 연결하기

Claude Code의 경우, claude mcp add CLI 명령을 사용하세요. 서버 이름과 실행 명령을 구분하기 위해 -- 구분자가 필요합니다:

claude mcp add github-tools \
  -e GITHUB_TOKEN=your_token \
  -e PYTHONUNBUFFERED=1 \
...

서버 설정을 팀과 공유하려면 --scope project를 사용하세요. 이렇게 하면 저장소 루트에 .mcp.json 파일이 작성되며, 팀원들이 프로젝트를 열 때 이를 활성화하도록 안내합니다. claude mcp list를 실행하여 등록을 확인하세요.

참고 문헌 (References)

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0