mcp_training

MCP 서버: 날씨, 지오코딩, 환율 도구를 제공하며, 이를 사용할 수 있는 OpenAI 모델과 대화하는 콘솔 클라이언트를 포함합니다.

Tú › ¿Qué tiempo hace en Madrid?

Modelo:
  En Madrid hay 24,3 °C, humedad del 41 % y cielo despejado.

  · get_lat_lon_from_city → get_current_weather

작동 방식

main_client.py ──> OpenAI (Responses API) ──> [túnel] ──> main_server.py (MCP)
   tu terminal        el modelo decide                     5 herramientas
                      qué herramientas usa                 sobre APIs públicas

클라이언트는 도구를 실행하지 않습니다. OpenAI에 MCP 서버의 공개 URL을 전달하면, OpenAI가 도구를 나열하고 호출하며 연결합니다(도시 → 좌표 → 날씨). 따라서 서버는 인터넷에서 접근 가능해야 합니다. OpenAI는 자신의 서버에서 연결하기 때문입니다.

도구

날씨 및 지오코딩은 Open-Meteo를 사용합니다(무료, 키 불필요). 환율은 ExchangeRate-API를 사용하며, 키가 필요하고 20개 통화를 지원합니다(CLI에서 /monedas).

구조

config/settings.py     configuración y logging (todo sale del .env)
server/                herramientas + clientes HTTP de las APIs externas
client/                cliente de OpenAI + interfaz de terminal
main_server.py         arranca el servidor MCP
main_client.py         arranca la conversación

Related MCP server: Python Weather MCP Server

설치

**Python 3.11+**가 필요합니다. uv 사용을 권장합니다:

git clone <url-del-repo>
cd mcp_training
uv sync

또는 pip와 가상 환경 사용:

python -m venv .venv
.venv\Scripts\activate        # Windows;  en Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt

설정

예제 파일을 복사하고 키를 입력하세요:

cp .env.example .env

필수 변수는 두 개뿐입니다:

그리고 세 번째 변수 MCP_PUBLIC_URL은 다음 단계에서 채워집니다. 나머지(모델, 포트, 전송, 타임아웃, 로그 수준)는 합리적인 기본값을 가지며 .env.example에 문서화되어 있습니다.

사용법

세 개의 터미널이 필요합니다: 서버, 터널, 클라이언트.

1. MCP 서버 시작

uv run python main_server.py

http://127.0.0.1:8002/mcp에서 수신 대기합니다.

2. 터널로 서버 공개

OpenAI가 서버에 접근하려면 공개 URL이 필요합니다. devtunnel 사용:

devtunnel port create -p 8002 --allow-anonymous
devtunnel host

출력된 URL(https://xxxxxxx-8002.euw.devtunnels.ms)을 복사하여 .env에 넣으세요:

MCP_PUBLIC_URL=https://xxxxxxx-8002.euw.devtunnels.ms

어떤 터널이든 상관없습니다(ngrok, Cloudflare Tunnel…). URL이 외부에서 접근 가능하기만 하면 됩니다. 클라이언트는 URL에 /mcp가 없으면 자동으로 추가합니다.

3. 클라이언트 실행

uv run python main_client.py

질문을 입력하고 Enter를 누르세요. 대화에는 메모리가 있습니다: 마드리드에 대해 물어본 후 "그리고 내일은?"이라고 말할 수 있습니다.

Convierte 100 USD a EUR
¿Cuál es el clima actual en Madrid?
Dame el pronóstico del tiempo para Nueva York

CLI 명령어:

클라이언트 없이 서버 사용하기

서버는 표준 MCP 서버입니다: 호환되는 모든 클라이언트에서 사용할 수 있습니다. 하위 프로세스로 연결하려면(Claude Desktop, Claude Code…), .env에 MCP_TRANSPORT=stdio를 설정하세요. 그러면 터널이나 포트가 필요 없습니다.

자주 발생하는 문제

각 호출의 세부 정보(인수, 응답, URL)를 보려면 .env에 LOG_LEVEL=DEBUG를 설정하세요. 로그는 stderr로 출력되므로 python main_client.py > charla.txt는 대화 내용만 저장합니다.