[AI] MCP(Model Context Protocol) 개념, 만드는 방법

MCP란?

MCP(Model Context Protocol) = AI가 외부 기능을 "도구(tool)"로 호출하는 표준 규격

• 클로드코드에서 "현재 날씨를 조회하는 기능"은 없지만, 내가 날씨를 조회하는 API가 있는 MCP를 만들어서 클로드코드에서 사용하면 날씨를 조회할수있음
• MCP는 클로드코드에서만 쓰는 용어

MCP 예시

브라우저/웹

• Playwright / Chrome DevTools MCP — 실제 브라우저 띄워서 UI 동작 확인, 스크린샷, 콘솔 로그 확인
• Brave Search / 웹서치 계열 — 최신 정보 검색

협업 툴

• Slack — 채널 메시지 읽기/보내기
• Notion — 문서 조회·수정
• Linear / Jira — 티켓 생성·조회, 스프린트 관리

데이터

• Postgres / SQLite — DB 스키마 조회, 쿼리 실행
• Filesystem — 프로젝트 밖 파일까지 다루고 싶을 때

디자인

• Figma — 디자인 스펙을 코드로 옮길 때 (컴포넌트 속성, 색상 등 조회)

모니터링/에러

• Sentry — 에러 로그 조회해서 바로 디버깅에 활용

MCP 만들어보기 1단계) - uv 패키지 준비

• uv 설치 확인
  
  • uv: Python용 패키지/프로젝트 관리 도구 (MCP 만드는데 사용)
  • Rust로 만들어져서 기존 도구들보다 훨씬 빠른 게 특징

uv --version

• uv가 없다면 설치

curl -LsSf https://astral.sh/uv/install.sh | sh

 

MCP 만들어보기 2단계) 초기화

• 현재 디렉토리가 ex-mcp라고 할때 아래 명령어를 통해 init 수행

uv init --no-readme --name ex-mcp .

결과)

ex_mcp/
├── .gitignore
├── .python-version   # 이 프로젝트가 쓸 파이썬 버전
├── main.py            # 기본 템플릿 파일 (hello world) — 나중에 지울 파일
└── pyproject.toml     # 프로젝트 설정 + 의존성 목록

• pyproject.toml 파일을 열면 아래처럼 버전 정보가 존재

[project]
name = "ex-mcp"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.11"
dependencies = []

• main.py을 열면 아래와 같은 코드 존재

def main():
    print("Hello from ex-mcp!")


if __name__ == "__main__":
    main()

MCP 만들어보기 3단계) fastmcp 준비

• mcp 기능을 만들기 위해 관련 패키지 설치

uv add fastmcp

• 위 명렁어 실행하면 아래 기능이 동작

1. .venv 가상환경 생성 (처음이면)
2. fastmcp와 의존 패키지들 설치
3. pyproject.toml의 dependencies에 fastmcp 추가
4. uv.lock 파일 생성 (정확한 버전 고정 — 나중에 다른 컴퓨터에서 uv sync만 하면 똑같이 재현됨)

• pyprojec.toml을 열면 아래처럼 dependencies에 fastmcp 확인이 가능

[project]
name = "ex-mcp"
version = "0.1.0"
description = "Add your description here"
requires-python = ">=3.11"
dependencies = [
    "fastmcp>=4.0.3",
]

MCP 만들어보기 4단계) mcp 코드 작성

• 안쓰는 main.py 파일 제거

rm main.py

• todo_mcp.py 생성
  • 만드려는 mcp: 개인 할일/메모 관리를 Claude Code 채팅에서 바로 할 수 있게 해주는 MCP 서버

% code todo_mcp.py

• 함수 작성
  • 작성 형태를 보면 @mcp.tool()을 각각 함수에다 추가하고, 내용들은 String형태로 작성
  • String형태로 args, returns 를 명확히 작성하면 AI가 알아서 수행함

import json
from pathlib import Path
from fastmcp import FastMCP

mcp = FastMCP("My Productivity MCP")

DATA_FILE = Path.home() / ".ex_mcp" / "data.json"


def _load() -> dict:
    if not DATA_FILE.exists():
        return {"todos": [], "notes": {}}
    return json.loads(DATA_FILE.read_text(encoding="utf-8"))


def _save(data: dict) -> None:
    DATA_FILE.parent.mkdir(parents=True, exist_ok=True)
    DATA_FILE.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")


@mcp.tool()
def todo_add(task: str) -> str:
    """새 할일을 추가한다.

    Args:
        task: 할일 내용

    Returns:
        추가 결과 메시지
    """
    data = _load()
    data["todos"].append({"task": task, "done": False})
    _save(data)
    return f"✅ 추가됨: {task}"


@mcp.tool()
def todo_list() -> str:
    """전체 할일 목록을 조회한다.

    Returns:
        번호가 매겨진 할일 목록 문자열
    """
    data = _load()
    if not data["todos"]:
        return "할일이 없습니다."
    lines = []
    for i, t in enumerate(data["todos"]):
        mark = "✔" if t["done"] else "☐"
        lines.append(f"{i}. [{mark}] {t['task']}")
    return "\n".join(lines)
    
if __name__ == "__main__":
    mcp.run()

MCP 만들어보기 5단계) 로컬 실행 테스트

• 파일이 잘 import 되는지 확인

uv run python -c "import todo_mcp; print('✅ import 성공')"
# 성공 시 출력됨 "✅ import 성공"

• 서버로 직접 실행

uv run python todo_mcp.py

# 정상이면 화면이 멈춘 것처럼 보이는 대기 상태로 들어감 (STDIO로 입력을 기다리는 중 — 에러 아님)
# Ctrl+C로 종료

• ctrl+C로 종료하고 아래 단계 수행

MCP 만들어보기 6단계) Claude Code에 등록

• claude code에 등록하는 명령어 수행
  • directory는 예제 디렉토리 경로로 작성
  • 로컬 서버로 todo_mcp가 실행하는 것

claude mcp add my-todo \
  -- uv --directory /Users/gimjong-gwon/ex_mcp \
  run python todo_mcp.py
  
# claude mcp add my-todo — my-todo라는 이름으로 MCP 서버 등록
# -- 뒤 — 이 서버를 실제로 어떻게 실행할지 (실행 커맨드)
# uv --directory ... run python todo_mcp.py — 해당 디렉토리에서 uv run python todo_mcp.py를 실행하라는 뜻 (Claude Code가 필요할 때 이 명령으로 서버를 띄움)

• 위 명령어는 해당 프로젝트 ex_mcp에 (local) 저장하는 방식이고, 만약 클로드코드 전역에 위 mcp를 사용할 수 있도록하려면 아래처럼 --scope user를 붙이면 됨

claude mcp add my-todo --scope user \
  -- uv --directory /Users/gimjong-gwon/ex_mcp \
  run python todo_mcp.py

저장위치) % code ~/.claude.json

mcp 전역 저장 된 모습 (~/.claude.json)

• 클로드 세션 다시 시작하기 위해서 클로드코드를 껐다 키고 아래 작업 수행
• claude code 채팅에 아래처럼 작성

todo_add("MCP 튜토리얼 끝내기")

• 또는 자연어로 아래처럼 작성

할일에 "MCP 튜토리얼 끝내기" 추가해줘

결과) 아래처럼 작성됨

• 할일 목록을 가져오기 위해서 "할일 목록 보여줘" 라고 클로드코드에 작성하면 아래처럼 답변이 잘 오는것 확인이 가능