mcp_training

Servidor MCP con herramientas de clima, geocodificación y divisas, y un cliente de consola que conversa con un modelo de OpenAI capaz de usarlas.

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

Cómo funciona

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

El cliente no ejecuta las herramientas: le pasa a OpenAI la URL pública del servidor MCP y es OpenAI quien las lista, las llama y las encadena (ciudad → coordenadas → clima). Por eso el servidor tiene que ser accesible desde internet: OpenAI se conecta desde sus servidores, no desde tu máquina.

Herramientas

Clima y geocodificación usan Open-Meteo (gratis, sin clave). Las divisas usan ExchangeRate-API, que sí requiere clave, y admiten 20 monedas (/monedas en la CLI).

Estructura

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

Instalación

Requiere Python 3.11+. Con uv (recomendado):

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

O con pip y un entorno virtual:

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

Configuración

Copia el ejemplo y rellena tus claves:

cp .env.example .env

Solo dos variables son obligatorias:

Y una tercera, MCP_PUBLIC_URL, que se rellena en el paso siguiente. Todo lo demás (modelo, puerto, transporte, timeouts, nivel de log) tiene valores por defecto sensatos y está documentado en .env.example.

Uso

Hacen falta tres terminales: servidor, túnel y cliente.

1. Arranca el servidor MCP

uv run python main_server.py

Queda escuchando en http://127.0.0.1:8002/mcp.

2. Publica el servidor con un túnel

OpenAI necesita una URL pública para llegar al servidor. Con devtunnel:

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

Copia la URL que imprime (https://xxxxxxx-8002.euw.devtunnels.ms) y ponla en el .env:

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

Vale cualquier túnel (ngrok, Cloudflare Tunnel…); solo importa que la URL sea accesible desde fuera. El cliente añade /mcp por su cuenta si no lo lleva.

3. Lanza el cliente

uv run python main_client.py

Escribe tu consulta y pulsa Enter. La conversación tiene memoria: tras preguntar por Madrid puedes decir simplemente «¿y mañana?».

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

Comandos de la CLI:

Usar el servidor sin el cliente

El servidor es un MCP estándar: sirve para cualquier cliente compatible. Para conectarlo como subproceso (Claude Desktop, Claude Code…) pon MCP_TRANSPORT=stdio en el .env; así no hacen falta ni el túnel ni el puerto.

Problemas frecuentes

Para ver el detalle de cada llamada (argumentos, respuestas, URLs) pon LOG_LEVEL=DEBUG en el .env. Los logs van a stderr, así que python main_client.py > charla.txt guarda solo la conversación.