MCP 서버 만들기｜파이썬으로 나만의 도구 서버 5단계 완성 입문 가이드
Claude가 내 앱을 직접 다루게 만드는 첫걸음
- MCP 서버 만들기는 파이썬 공식 SDK 하나만 있으면 30분 안에 시작할 수 있습니다.
- 도구(Tool) 하나를 정의하는 코드는 함수 하나에 데코레이터 한 줄이면 충분합니다.
- 완성한 서버는 claude_desktop_config.json에 경로만 등록하면 바로 연결됩니다.
- 초보자가 자주 겪는 실행 오류 3가지와 해결법을 실제 사례로 정리했습니다.
노션이나 구글 캘린더처럼 이미 나온 MCP 서버는 많은데, 정작 내가 매일 쓰는 사내 시스템이나 개인 스크립트에는 연결할 게 없어서 아쉬웠던 적 있으신가요.
그럴 때 필요한 게 MCP 서버 만들기입니다. 남이 만든 도구를 가져다 쓰는 것에서 한 발 더 나아가, 내가 원하는 기능을 Claude가 직접 호출하도록 만드는 작업입니다.
이 글은 파이썬 기초만 아는 분도 따라 할 수 있게, 개발 환경 준비부터 첫 도구 코드 작성, Claude Desktop 연결, 자주 나는 오류 해결까지 순서대로 다룹니다.
MCP 서버 만들기, 왜 직접 해봐야 할까
MCP(Model Context Protocol)는 AI 모델과 외부 도구·데이터를 표준화된 방식으로 연결하는 오픈 프로토콜입니다. Claude, Cursor 같은 클라이언트가 이 규격을 따르는 서버라면 무엇이든 도구처럼 호출할 수 있습니다.
공개된 MCP 서버만 써도 파일 시스템, 깃허브, 데이터베이스 정도는 충분히 다룰 수 있습니다. 문제는 회사 내부 API나 개인 자동화 스크립트처럼 아무도 만들어 두지 않은 영역입니다.
이럴 때 직접 서버를 만들면, Claude에게 “이 스프레드시트 최신 값 가져와서 요약해줘” 같은 요청을 실제 함수 실행으로 연결할 수 있습니다. 프롬프트로 설명하는 대신 코드로 동작을 정의하는 셈입니다.
MCP 서버 만들기와 일반 API 연동의 차이는 “누가 판단하느냐”에 있습니다. REST API는 개발자가 호출 순서를 코드로 짜야 하지만, MCP 서버는 도구 설명만 등록해두면 Claude가 대화 맥락을 보고 언제 어떤 도구를 쓸지 스스로 판단합니다.
개발 환경 준비하기
가장 먼저 파이썬이 설치돼 있는지 확인합니다. 터미널에 python –version을 입력해 3.10 이상이면 충분합니다.
프로젝트 폴더를 하나 만들고 가상 환경을 켠 다음, 공식 MCP 파이썬 SDK를 설치합니다. 명령어는 아래와 같습니다.
터미널 명령어 순서
1. mkdir my-mcp-server && cd my-mcp-server
2. python -m venv venv
3. source venv/bin/activate (윈도우는 venv\Scripts\activate)
4. pip install mcp
SDK 설치 후 pip show mcp로 버전을 확인해두면, 나중에 동작이 이상할 때 SDK 업데이트 문제인지 코드 문제인지 구분하기 쉽습니다.
에디터는 VS Code를 추천합니다. 파이썬 확장을 깔아두면 타입 힌트 오류를 바로바로 잡아줘서 MCP 서버 만들기 과정에서 실수를 줄일 수 있습니다.
서버 코드를 담을 server.py 파일 하나만 있어도 시작하기에는 충분합니다. 기능이 늘어나면 tools 폴더로 나누면 됩니다.
가상 환경을 켜지 않은 채로 pip install을 하면 전역 파이썬 환경에 패키지가 깔립니다. 다른 프로젝트와 버전이 꼬일 수 있으니 venv 활성화 여부를 항상 프롬프트 앞부분(venv)로 확인하세요.
파이썬으로 MCP 서버 만들기: 첫 번째 도구 코드
공식 SDK는 FastMCP라는 고수준 클래스를 제공합니다. 함수 하나에 데코레이터만 붙이면 그 함수가 바로 Claude가 호출할 수 있는 도구가 됩니다.
아래는 두 숫자를 더하는 아주 단순한 도구 예시입니다. MCP 서버 만들기의 가장 작은 단위가 이 형태입니다.
기본 서버 코드 예시
from mcp.server.fastmcp import FastMCP
mcp = FastMCP(“my-first-server”)
@mcp.tool()
def add_numbers(a: int, b: int) -> int:
“””두 숫자를 더합니다.”””
return a + b
if __name__ == “__main__”:
mcp.run(transport=”stdio”)
함수 이름, 타입 힌트, docstring이 그대로 Claude에게 전달되는 도구 설명이 됩니다. 이름을 대충 짓거나 docstring을 비워두면 Claude가 언제 이 도구를 써야 할지 판단하기 어려워집니다.
도구 이름은 동사로 시작하는 게 좋습니다. get_weather, search_files처럼 “무엇을 하는지”가 이름에 드러나야, 비슷한 도구가 여러 개일 때도 Claude가 헷갈리지 않고 고릅니다.
파일을 읽거나 API를 호출하는 실전 도구를 만들 때도 구조는 똑같습니다. 함수 안에서 원하는 로직을 실행하고 결과를 문자열이나 딕셔너리로 반환하면 됩니다.
Claude Desktop에 연결하고 테스트하기
서버 코드를 다 썼다면 이제 Claude Desktop이 이 서버를 실행하도록 설정 파일에 등록할 차례입니다.
맥에서는 ~/Library/Application Support/Claude/claude_desktop_config.json, 윈도우에서는 %APPDATA%\Claude\claude_desktop_config.json 파일을 엽니다. 파일이 없으면 새로 만들면 됩니다.
설정 파일 작성 예시
{
“mcpServers”: {
“my-first-server”: {
“command”: “python”,
“args”: [“/전체경로/my-mcp-server/server.py”]
}
}
}
command에는 가상 환경 안의 python 실행 파일 경로를, args에는 server.py의 절대 경로를 정확히 적어야 합니다. 상대 경로는 인식되지 않습니다.
윈도우 경로는 역슬래시(\)를 두 번(\\) 써야 JSON에서 오류가 나지 않습니다. 예: C:\\Users\\사용자\\my-mcp-server\\server.py
파일을 저장한 뒤 Claude Desktop을 완전히 종료했다가 다시 켭니다. 새로고침만으로는 설정이 반영되지 않는 경우가 많습니다.
정상적으로 연결되면 채팅 입력창 근처에 망치 아이콘이 나타납니다. 이 아이콘을 눌러 등록한 도구 목록이 보이면 성공입니다.
“1+1이 아니라 add_numbers 도구로 3과 5를 더해줘”처럼 도구 이름을 언급하며 요청해보면, Claude가 실제로 함수를 호출하는지 눈으로 확인할 수 있습니다.
자주 하는 실수와 디버깅 팁
망치 아이콘이 아예 안 뜬다면 십중팔구 JSON 문법 오류입니다. 쉼표 하나만 빠져도 설정 전체가 무시됩니다. 온라인 JSON 검증 도구에 붙여넣어 확인하는 습관을 들이면 좋습니다.
도구는 보이는데 호출하면 오류가 난다면, 가상 환경이 아닌 시스템 파이썬 경로가 등록됐을 가능성이 큽니다. which python(맥) 또는 where python(윈도우)으로 정확한 경로를 다시 확인합니다.
함수는 실행되는데 Claude가 도구를 안 쓰고 그냥 답변만 한다면, docstring이 모호하거나 함수 이름이 역할을 설명하지 못하는 경우가 많습니다. 이름과 설명을 더 구체적으로 다듬어 봅니다.
디버깅이 막막할 때는 터미널에서 python server.py를 직접 실행해보세요. Claude Desktop을 거치지 않고도 문법 오류나 임포트 실패를 바로 확인할 수 있어서, 원인을 훨씬 빨리 좁힐 수 있습니다.
어느 정도 익숙해졌다면 FastMCP 같은 상위 프레임워크로 넘어가 도구를 더 빠르게 늘려가는 것도 방법입니다. 다만 처음에는 공식 SDK로 기본 동작 원리를 직접 익히는 쪽을 추천합니다.
아니요. 공식 SDK는 타입스크립트로도 제공됩니다. 다만 문법이 간단하고 예제가 많아 입문 단계에서는 파이썬이 더 수월합니다.
네, stdio 방식으로 로컬에서 실행하면 인터넷에 올릴 필요 없이 내 컴퓨터 안에서만 동작합니다. 개인용으로는 이 방식이 가장 간단합니다.
같은 mcp 객체에 @mcp.tool() 데코레이터를 붙인 함수를 계속 추가하면 됩니다. 함수마다 이름과 설명만 겹치지 않게 관리하면 됩니다.
네, MCP 도구 안에서 n8n의 웹훅 URL을 호출하도록 짜면 Claude 대화 한 줄로 n8n 워크플로우를 실행시킬 수 있습니다.
서버 코드를 직접 짜는 만큼 접근 권한도 직접 통제할 수 있습니다. 함수 안에서 읽기·쓰기 범위를 명시적으로 제한하면 필요 이상의 권한을 주지 않을 수 있습니다.
📚 함께 보면 좋은 글
MCP 개념부터 자동화 파이프라인까지, 이어서 보면 좋은 글들입니다.
🔗 공식 자료
📖 출처
– Model Context Protocol 공식 문서 (modelcontextprotocol.io)
– MCP Python SDK 깃허브 저장소 (github.com/modelcontextprotocol/python-sdk)
– Anthropic Claude 개발자 문서 (docs.claude.com)
– Claude Desktop MCP 연결 가이드 자료
– FastMCP 프레임워크 공식 릴리스 노트
MCP 서버 만들기는 함수 하나에 데코레이터를 붙이는 것에서 시작합니다. 공식 파이썬 SDK로 도구를 정의하고, 설정 파일 경로만 정확히 맞추면 Claude가 내 컴퓨터의 기능을 직접 호출하게 됩니다.
