MCP: Build an MCP server

MCP 서버 실행 및 예제 (Windows 기준)

(Windows · uv · PowerShell 기준)

1. 목적

본 문서는 Windows 환경에서 MCP(Model Context Protocol) 서버를 설치하고, 실행 및 테스트까지 완료하는 최소 예제 흐름을 정리한다.
목표는 다음 세 가지이다.

1. MCP 서버가 정상적으로 기동되는지 확인
2. MCP Tool이 호스트(예: Claude for Desktop)에서 인식되는지 검증
3. 이후 AAIF 표준 기반 PoC로 확장 가능한 상태 확보

참고: MCP의 기본 예제는 STDIO(JSON-RPC) 기반이다.
즉, 서버는 사용자가 직접 콘솔에서 조작하는 형태가 아니라, MCP 호스트(클라이언트)가 프로세스를 띄우고 stdin/stdout으로 통신하는 구조다.

2. 사전 환경

• OS: Windows 10/11

• Shell: PowerShell

• Python: 3.10 이상 권장

• 패키지 매니저: uv (Astral)

3. uv 설치 (Windows)

3.1 설치 명령

PowerShell에서 실행:

irm https://astral.sh/uv/install.ps1 | iex

설치 로그 예시:

Installing to C:\Users\<USER>\.local\bin
  uv.exe
  uvx.exe
  uvw.exe
everything's installed!

3.2 PATH 문제 해결 (중요)

Windows에서는 설치 직후 uv가 인식되지 않는 경우가 있다.

설치 경로는 다음과 같다.

C:\Users\<USER>\.local\bin

(1) 즉시 사용용 – 현재 세션 PATH 추가

$env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
uv --version

(2) 영구 등록 (권장)

setx PATH "$env:PATH;$env:USERPROFILE\.local\bin"

이후 PowerShell을 완전히 종료 후 재실행하고 확인:

uv --version

4. MCP 프로젝트 초기화

4.1 프로젝트 생성

cd C:\AAIF
uv init weather
cd weather

4.2 가상환경 생성 및 활성화

uv venv
.venv\Scripts\activate

정상일 경우 프롬프트에 다음 표시가 나타난다.

(.venv) PS C:\AAIF\weather>

4.3 MCP 및 의존성 설치

uv add mcp[cli] httpx

설치 목적:

• mcp[cli] : MCP 서버 및 CLI 도구
• httpx : 이후 외부 API 연동용 (확장 대비)

5. MCP 서버 예제 코드

5.1 서버 파일 생성

New-Item weather.py

5.2 최소 MCP 서버 코드 (Mock)

# weather.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather-server")


@mcp.tool()
def get_weather(city: str) -> str:
    """Return mock weather information for a given city."""
    return f"The weather in {city} is sunny."


def main():
    # STDIO(JSON-RPC) 기반: 호스트가 서버 프로세스를 띄우고 통신한다.
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()

설명:

• FastMCP는 tool decorator + 타입힌트 기반으로 tool 스키마를 구성

• 실제 API 호출 없이 mock 응답으로 동작 검증

• STDIO 서버는 stdout 오염(예: print) 시 JSON-RPC가 깨질 수 있으므로 출력 주의

6. MCP 서버 실행 (중요: “직접 실행”은 권장되지 않음)

6.1 권장 실행 방식: uv로 실행 (호스트가 붙는 전제)

uv run weather.py

이 상태에서 서버는 stdin으로 JSON-RPC 메시지가 들어오길 대기한다.
따라서 “실행 후 콘솔이 멈춘 것처럼 보이는 것”은 정상이다.

6.2 비권장: python weather.py 단독 실행

python weather.py

STDIO 서버를 단독 실행하면, 입력이 없거나(EOF) 콘솔 입력이 들어가면서 Invalid JSON: EOF ... 같은 오류가 날 수 있다.

이는 서버 코드 문제가 아니라 STDIO 통신 방식 특성이다.

7. 테스트 방법 (현재 CLI/환경 기준)

핵심: 일부 환경에서는 mcp inspect, mcp call 같은 서브커맨드가 존재하지 않을 수 있다(버전/패키징 차이).
따라서 “호스트 연동 테스트”를 1순위로 둔다.

7.1 Claude for Desktop로 테스트 (권장)

Claude for Desktop 설정 파일 경로(Windows):

code $env:AppData\Claude\claude_desktop_config.json

예시 설정:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\AAIF\\weather",
        "run",
        "weather.py"
      ]
    }
  }
}

주의사항:

• 경로는 반드시 절대경로

• Windows JSON 경로는 \\ 이스케이프 필요

• uv가 PATH에 안 잡히면 where uv로 나온 절대경로를 command에 넣는다.

Claude for Desktop을 완전히 종료 후 재시작하면, Tool 목록에 get_weather가 노출되어야 한다.

7.2 MCP CLI가 dev를 제공하는 경우 (선택)

mcp --help로 가능한 명령을 확인한 후, dev가 있고 FILE_SPEC 형식을 요구한다면 보통 아래처럼 실행한다:

mcp dev python:weather.py

mcp dev python weather.py 형태는 FILE_SPEC 규격과 달라 실패할 수 있다.

8. 자주 발생하는 Windows 이슈 요약

이슈	원인	해결
uv 인식 안 됨	PATH 미등록	$env:USERPROFILE\.local\bin PATH 추가 / setx 후 재실행
가상환경 활성화 실패	실행 정책	Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
STDIO 서버 실행 시 JSON 오류	호스트 없이 단독 실행 / stdin 오염	uv run weather.py는 “대기”가 정상, 테스트는 호스트(Claude)로 수행
mcp inspect/call 없음	CLI 버전/구성 차이	mcp --help 기준으로 dev/run 사용 또는 Claude로 테스트

9. 현재 단계의 의미 (AAIF 관점)

이 상태는 다음을 의미한다.

• MCP 서버 최소 단위 PoC 완료

• Tool schema 기반 자동화 가능성 검증

• 이후 다음 단계로 자연스럽게 확장 가능 (예: 실제 API 연동, 문서 자동화 Tool, 리포트 생성 파이프라인)

::contentReference[oaicite:0]{index=0}