Asistente de Monedas y Clima — Servidor MCP + Cliente OpenAI

Proyecto que expone un servidor MCP (Model Context Protocol) con 5 herramientas que integran dos APIs públicas — ExchangeRate-API (conversión de monedas) y Open-Meteo (geocodificación y clima) — y un cliente que usa la API Responses de OpenAI con soporte nativo para herramientas MCP remotas, expuesto a través de una interfaz de línea de comandos (CLI) en lenguaje natural.

Arquitectura

Usuario (CLI) → Cliente OpenAI (Responses API) → Servidor MCP local → APIs externas
                                                    (ExchangeRate-API, Open-Meteo)

El modelo decide qué herramientas llamar y en qué orden. Para preguntas de clima, sigue este flujo:

1. geocode_city("Madrid") → obtiene latitud/longitud

2. get_current_weather(lat, lon) → obtiene el clima actual

3. El modelo redacta la respuesta final combinando ambos resultados

Related MCP server: Currency Converter MCP

Estructura del proyecto

├── server/
│   ├── mcp_server.py           # Servidor MCP con las 5 herramientas (FastMCP)
│   ├── currency_tools.py       # Lógica de conversión de monedas
│   ├── weather_tools.py        # Lógica de clima actual y pronóstico
│   ├── geocoding_tools.py      # Lógica de geocodificación
│   └── api_clients.py          # Clientes HTTP de bajo nivel para las APIs
├── client/
│   ├── openai_client.py        # Cliente OpenAI (Responses API + MCP remoto)
│   └── cli_interface.py        # Interfaz de línea de comandos
├── config/
│   └── settings.py             # Configuración centralizada (.env)
├── main_server.py               # Punto de entrada del servidor
├── main_client.py                # Punto de entrada del cliente
├── requirements.txt
├── .env.example
└── README.md

Herramientas del servidor MCP

Requisitos previos

• Python 3.10 o superior

• Una API key gratuita de ExchangeRate-API

• Una API key de OpenAI con acceso a un modelo compatible con Responses API + MCP remoto (gpt-4.1, gpt-4o, gpt-5 o similar)

• Open-Meteo no requiere API key

Instalación

1. Clona o descarga este proyecto y entra en la carpeta:

   cd mcp_project

2. Crea un entorno virtual (recomendado):

   python3 -m venv venv
   source venv/bin/activate   # En Windows: venv\Scripts\activate

3. Instala las dependencias:

   pip install -r requirements.txt

4. Copia el fichero de variables de entorno y complétalo con tus claves:

   cp .env.example .env

   Edita .env y define, como mínimo:

   API_KEY_EXCHANGE=tu_api_key_de_exchangerate
   OPENAI_API_KEY=tu_api_key_de_openai

Uso

1. Arrancar el servidor MCP

En una terminal:

python main_server.py

Por defecto el servidor escucha en http://127.0.0.1:8000/mcp. Verás un mensaje de log confirmando el arranque y las herramientas registradas.

2. Arrancar el cliente CLI

En otra terminal (con el mismo entorno virtual activado):

python main_client.py

Aparecerá un menú de bienvenida. Ejemplos de preguntas que puedes escribir directamente en lenguaje natural:

Tú: Convierte 100 USD a EUR
Tú: ¿Cuál es el clima actual en Madrid?
Tú: Dame el pronóstico del tiempo para Nueva York
Tú: ¿Qué coordenadas tiene Tokio?
Tú: Dame las tasas de cambio del USD frente a EUR, GBP y JPY

Comandos especiales

Configuración avanzada

Todas las variables se leen desde .env (ver .env.example):

Manejo de errores

• Servidor MCP: cada herramienta valida sus parámetros de entrada (montos negativos, códigos de moneda inválidos, coordenadas fuera de rango, ciudades vacías) y captura errores de red, timeouts y códigos de estado HTTP de las APIs externas, devolviendo un mensaje de error claro en lugar de propagar una excepción sin control.

• Cliente OpenAI: implementa reintentos con backoff exponencial ante errores de conectividad (APIConnectionError, APITimeoutError) y límites de uso (RateLimitError), y reporta errores irrecuperables de forma clara en la CLI.

• CLI: captura ciudades no encontradas, entradas vacías e interrupciones de teclado (Ctrl+C) sin cerrar el programa abruptamente.

Notas

• Open-Meteo es completamente gratuita y no requiere autenticación.

• ExchangeRate-API requiere una API key gratuita (plan "Free") que puedes obtener en su web.

• El servidor debe estar corriendo antes de iniciar el cliente.