Claude Code MCP 서버가 뭔가요?
Claude Code를 쓰다 보면 한 가지 아쉬운 점이 생깁니다. “이걸 WordPress에 바로 올릴 수 없나?”, “Slack에 알림을 보내고 싶은데?” 같은 생각이요. 저도 처음에는 Claude가 터미널에서만 코드를 짜는 도구인 줄 알았습니다.
그런데 MCP 서버를 만들면 얘기가 달라집니다.
MCP(Model Context Protocol)는 Claude Code가 외부 서비스와 통신하는 표준 프로토콜입니다. 쉽게 말해, Claude에게 “이 함수를 쓰면 WordPress에 글을 올릴 수 있어”라고 알려주는 연결 통로입니다. 제가 직접 만들어보니, WordPress 글 발행부터 SEO 최적화까지 전부 자동화할 수 있었습니다. MCP의 전체 스펙이 궁금하다면 공식 MCP 문서를 참고하세요.
왜 직접 만들어야 할까?
Anthropic에서 공식 제공하는 MCP 서버도 있습니다. GitHub, Slack, PostgreSQL 같은 서비스용이요. 하지만 문제는 “내 워크플로우”에 딱 맞는 서버는 없다는 겁니다.
저의 경우를 예로 들면:
- 블로그 글을 쓰면 자동으로 RankMath SEO 메타를 설정하고 싶었습니다
- 이미지를 Pexels에서 검색해서 바로 WordPress에 업로드하고 싶었습니다
- 기존 글과 키워드가 겹치는지 자동으로 체크하고 싶었습니다
이런 건 범용 MCP 서버로는 안 됩니다. 직접 만들어야 합니다.
준비물 — 3가지면 충분합니다
Claude Code MCP 서버를 만들기 위해 필요한 건 딱 3가지입니다:
- Python 3.10+ — 이미 설치되어 있을 겁니다
- FastMCP — MCP 서버를 쉽게 만들어주는 Python 라이브러리
- 연결할 서비스의 API — WordPress REST API, Slack API 등
설치는 한 줄이면 됩니다:
pip install fastmcp httpx python-dotenvhttpx는 HTTP 요청용, python-dotenv는 API 키 관리용입니다.
5분 만에 첫 MCP 서버 만들기
제가 처음 만들었던 서버를 그대로 보여드리겠습니다. 파일 하나면 됩니다.
"""내 첫 MCP 서버"""
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("my-tools")
@mcp.tool()
def hello(name: str) -> str:
"""인사하는 도구입니다."""
return f"안녕하세요, {name}님! MCP 서버에서 보내는 인사입니다."
@mcp.tool()
def calculate_bmi(weight_kg: float, height_cm: float) -> str:
"""BMI를 계산합니다."""
height_m = height_cm / 100
bmi = weight_kg / (height_m ** 2)
return f"BMI: {bmi:.1f}"
if __name__ == "__main__":
mcp.run()이게 전부입니다. @mcp.tool() 데코레이터를 붙이면 Claude가 해당 함수를 도구로 인식합니다. 함수의 docstring이 도구 설명이 되고, 파라미터 타입 힌트가 입력 스키마가 됩니다.
Claude Code에 등록하고 실행하기
서버를 만들었으면 Claude Code에 알려줘야 합니다. 터미널에서 이 명령어 하나면 됩니다:
claude mcp add my-tools -s user -- python my_server.py각 옵션의 의미:
my-tools— MCP 서버 이름 (원하는 대로)-s user— 사용자 수준 등록 (모든 프로젝트에서 사용 가능)-- python my_server.py— 서버 실행 명령
등록하고 Claude Code를 다시 열면, Claude가 자동으로 hello와 calculate_bmi 도구를 인식합니다. “BMI 계산해줘”라고 말하면 알아서 도구를 호출합니다.
실전 예시 — WordPress 연동
간단한 예시를 넘어서, 제가 실제로 사용 중인 WordPress MCP 서버의 핵심 패턴을 공유합니다.
import base64
import httpx
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("wordpress")
WP_URL = "https://your-site.com"
WP_USER = "admin"
WP_PASS = "xxxx xxxx xxxx xxxx" # 애플리케이션 비밀번호
def _auth():
token = base64.b64encode(f"{WP_USER}:{WP_PASS}".encode()).decode()
return {"Authorization": f"Basic {token}"}
@mcp.tool()
def wp_create_post(title: str, content: str, status: str = "draft") -> str:
"""WordPress에 새 글을 생성합니다."""
r = httpx.post(
f"{WP_URL}/wp-json/wp/v2/posts",
headers={**_auth(), "Content-Type": "application/json"},
json={"title": title, "content": content, "status": status},
timeout=30,
)
if r.status_code == 201:
data = r.json()
return f"✅ 글 생성 완료! ID: {data['id']}, URL: {data['link']}"
return f"❌ 실패: HTTP {r.status_code}"이 패턴만 알면 어떤 REST API든 MCP 도구로 만들 수 있습니다. Slack 메시지 보내기, Notion 페이지 생성, GitHub 이슈 등록 — 전부 같은 구조입니다.
도구 설계 팁과 실전 운영 경험
제가 18개 도구를 만들면서 깨달은 점이 있습니다.
함수 이름과 docstring이 핵심입니다. Claude는 도구를 선택할 때 이름과 설명을 보고 판단합니다. do_stuff() 같은 이름은 쓰지 마세요. wp_create_post()처럼 동작이 명확한 이름을 쓰세요.
반환값은 문자열로 통일하세요. MCP 도구의 반환값은 결국 Claude가 읽는 텍스트입니다. JSON을 그대로 던지지 말고, 사람이 읽기 쉬운 마크다운으로 포맷팅해서 돌려주세요.
에러 메시지를 친절하게 쓰세요. Claude가 에러를 받으면 다음 행동을 결정해야 합니다. “실패”보다 “❌ 인증 실패 — 애플리케이션 비밀번호를 확인하세요”가 훨씬 낫습니다.
환경변수로 인증 정보를 관리하세요. API 키를 코드에 하드코딩하지 마세요. .env 파일 + python-dotenv를 쓰면 됩니다.
참고로 제가 실제 운영 중인 WordPress SEO MCP 서버는 키워드 리서치, 카니발리제이션 체크, 스타일 DNA 추출, SEO 체크+수정 제안, 3단계 내부 링크 추천, AI 문체 감지, 이미지 검색+업로드, 원클릭 파이프라인까지 총 18개 도구가 들어 있습니다. “이 주제로 글 써줘” 한마디면 키워드 리서치부터 예약 발행까지 전부 자동으로 돌아갑니다.
자주 하는 실수와 해결법
처음 MCP 서버를 만들 때 제가 겪었던 삽질을 공유합니다.
Windows에서 인코딩 에러가 나요. Python이 cp949로 출력하려다 이모지에서 터집니다. 환경변수에 PYTHONIOENCODING=utf-8을 추가하세요.
도구가 Claude Code에서 안 보여요. claude mcp list로 서버 상태를 확인하세요. “Connected”가 아니면 서버 파일 경로가 잘못된 겁니다.
API 호출이 타임아웃 나요. httpx의 기본 타임아웃은 5초인데, WordPress 같은 서비스는 느릴 수 있습니다. timeout=30으로 넉넉하게 잡으세요.
도구를 수정했는데 반영이 안 돼요. MCP 서버를 재시작해야 합니다. Claude Code에서 /mcp 명령어로 재연결하면 됩니다.
마치며 — 한 번 만들면 계속 씁니다
Claude Code MCP 서버는 한 번 만들어두면 매일 씁니다. 저는 블로그 글 하나 쓰는 데 키워드 리서치부터 발행까지 5분이면 끝납니다. 예전에는 2시간 걸리던 작업입니다.
핵심은 간단합니다:
- FastMCP로 Python 파일 만들고
@mcp.tool()로 함수 등록하고claude mcp add로 Claude Code에 연결
이 3단계만 기억하세요. 나머지는 연결하고 싶은 API만 바꾸면 됩니다. WordPress든, Slack이든, Notion이든 — 구조는 똑같습니다.
코드가 궁금하시면 GitHub에 제가 만든 WordPress MCP 서버를 공개해뒀으니 참고하세요.