MCP 서버 직접 만들기 — 내 도구를 Claude에 연결하는 최소 예제

7월 26, 2026

Claude를 쓰다 보면 "내 컴퓨터의 파일을 읽게 하고 싶다", "우리 회사 DB를 조회하게 하고 싶다"는 순간이 온다. 이걸 표준 방식으로 해결하는 것이 MCP(Model Context Protocol)다. 이번 글에서는 도구 1개짜리 최소 MCP 서버를 파이썬으로 직접 만들고, Claude Desktop과 Claude Code에 연결해 실제로 동작시키는 과정을 순서대로 정리한다. 전체 코드는 15줄이 안 된다.

MCP가 뭔가 — 모델과 도구를 잇는 프로토콜

MCP는 AI 모델(정확히는 Claude 같은 클라이언트 앱)과 외부 도구·데이터를 연결하는 표준 규격이다. 예전에는 앱마다 플러그인 방식이 제각각이라 같은 기능을 여러 번 만들어야 했는데, MCP는 "도구 목록을 알려주는 방법"과 "도구를 호출하고 결과를 돌려받는 방법"을 표준으로 정해 두었다. 그래서 MCP 서버를 하나 만들면 Claude Desktop, Claude Code 등 MCP를 지원하는 여러 클라이언트에 같은 서버를 꽂아 쓸 수 있다.

구조는 단순하다. Claude가 클라이언트, 내가 만드는 프로그램이 서버다. 서버는 "나는 이런 도구를 갖고 있다"고 목록을 알려주고, 모델이 대화 중 필요하다고 판단하면 도구를 호출한다. 서버는 요청을 실행해 결과를 돌려주고, 모델은 그 결과를 바탕으로 답을 이어간다.

준비물과 최소 서버 골격

파이썬 공식 SDK를 쓴다. SDK에 포함된 FastMCP 클래스를 쓰면 데코레이터 하나로 도구를 등록할 수 있다. 파이썬 3.10 이상이 필요하다.

작업 폴더를 하나 만든다. 예: C:\work\mcp-memo
터미널에서 SDK를 설치한다.

pip install "mcp[cli]"

그리고 server.py 파일을 만든다. 아래가 전체 코드다. "메모를 파일에 저장하는" 도구 하나만 가진 서버다.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("memo-server")

@mcp.tool()
def save_memo(text: str) -> str:
    """메모 한 줄을 파일에 저장한다."""
    with open(r"C:\work\mcp-memo\memo.txt", "a", encoding="utf-8") as f:
        f.write(text + "\n")
    return "저장 완료: " + text

if __name__ == "__main__":
    mcp.run()

mcp.run()은 기본적으로 stdio 방식으로 동작한다. 클라이언트(Claude)가 이 스크립트를 자식 프로세스로 실행하고 표준 입출력으로 대화하는 구조라서, 포트를 열거나 웹서버를 띄울 필요가 없다.

도구 정의 — 입력 스키마는 자동으로 만들어진다

핵심은 @mcp.tool() 데코레이터다. 여기서 세 가지가 자동으로 처리된다.

함수 이름이 도구 이름이 된다 (save_memo).
타입 힌트(text: str)가 입력 스키마로 변환된다. 모델은 이 스키마를 보고 어떤 인자를 넘겨야 하는지 안다.
docstring이 도구 설명이 된다. 모델이 "언제 이 도구를 쓸지" 판단하는 근거라서, 설명을 구체적으로 쓸수록 호출 정확도가 올라간다.

JSON 스키마를 손으로 쓸 필요가 없다는 것이 FastMCP 방식의 가장 큰 장점이다. 인자를 여러 개 받고 싶으면 그냥 함수 인자를 늘리면 된다.

Claude Desktop에 연결하기

Claude Desktop은 설정 파일에 서버를 등록하는 방식이다.

Claude Desktop에서 설정 → 개발자(Developer) 탭 → Edit Config를 누른다. 설정 파일 위치가 열린다. 직접 찾는다면 윈도우는 %APPDATA%\Claude\claude_desktop_config.json, 맥은 ~/Library/Application Support/Claude/claude_desktop_config.json이다.
파일에 아래 내용을 넣는다. 경로는 본인 환경에 맞게 바꾼다.

{
  "mcpServers": {
    "memo-server": {
      "command": "python",
      "args": ["C:\\work\\mcp-memo\\server.py"]
    }
  }
}

Claude Desktop을 완전히 종료하고 다시 실행한다. 창만 닫으면 백그라운드에 남아 있어서 설정이 반영되지 않는다. 트레이 아이콘에서 종료해야 한다.

주의할 점이 하나 있다. JSON 안의 윈도우 경로는 역슬래시를 \\로 두 번 써야 한다. 여기서 한 번 이상 막히는 경우가 많다.

Claude Code에 연결하기

Claude Code는 터미널 명령 한 줄이면 된다. 프로젝트 폴더에서 실행한다.

claude mcp add memo-server -- python C:\work\mcp-memo\server.py

-- 뒤가 서버를 실행하는 명령이다. 등록 범위(scope)는 세 가지가 있는데, 기본은 현재 프로젝트에서 나만 쓰는 local이다. 팀과 공유하려면 --scope project를 붙이면 프로젝트 루트의 .mcp.json에 기록되어 git으로 공유할 수 있고, 모든 프로젝트에서 쓰려면 --scope user를 쓴다. 등록 후 Claude Code 안에서 /mcp를 입력하면 서버 연결 상태와 도구 목록을 확인할 수 있다.

실제 동작 확인

연결이 끝났으면 테스트해 본다.

Claude Desktop이라면 입력창 근처의 도구 아이콘에서 memo-server가 보이는지 확인한다.
대화창에 이렇게 입력한다: "오늘 배운 것: MCP 서버 만들기 — 라고 메모 저장해줘"
Claude가 save_memo 도구를 호출하겠다고 허가를 요청한다. 승인하면 실행된다.
memo.txt 파일을 열어 내용이 실제로 기록됐는지 확인한다.

여기까지 되면 성공이다. 만약 서버가 목록에 안 보이면 순서대로 점검한다. 첫째, 터미널에서 python C:\work\mcp-memo\server.py를 직접 실행해 에러 없이 대기 상태가 되는지 확인한다. 둘째, 설정 파일의 JSON 문법(쉼표, 따옴표, 역슬래시)을 확인한다. 셋째, 파이썬이 PATH에 없는 환경이라면 command에 파이썬 전체 경로를 적는다.

다음 단계 — 도구 말고도 리소스와 프롬프트가 있다

MCP에는 도구(tool) 외에 두 가지 개념이 더 있다.

리소스(resource): 모델이 읽을 수 있는 데이터를 노출한다. 함수 호출이 아니라 "읽기 전용 문서"에 가깝다. 설정 파일, 로그, DB 조회 결과 같은 것을 컨텍스트로 제공할 때 쓴다.
프롬프트(prompt): 자주 쓰는 지시문 템플릿을 서버가 제공한다. 클라이언트에서 골라 쓰는 정형화된 명령이라고 보면 된다.

먼저 도구 하나짜리 서버로 전체 흐름을 몸에 익히고, 그다음 실제로 반복하는 업무 하나를 도구로 만들어 보는 순서를 추천한다. 파일 정리, 사내 API 조회, 로그 검색처럼 매일 하는 일이 가장 좋은 첫 소재다.

※ 이 글의 SDK 사용법, 설정 파일 위치, 명령어 문법은 2026년 기준이며 변경될 수 있습니다.

함께 보면 좋은 글: 안드로이드 스튜디오에서 Claude Code 사용하는 방법

이 블로그 검색

에이븐스튜디오