Finance and weather assistant with MCP

Command-line application that combines a local MCP server with the OpenAI Responses API. The assistant understands natural language queries, discovers the tools published by the server, and executes them to query current currency and weather data.

The project integrates FastMCP, ExchangeRate-API and Open-Meteo. It also supports chained calls: for example, it converts a city name into coordinates and then queries its current weather or forecast.

Features

• Conversion of amounts between currencies using ISO 4217 codes.

• Query exchange rates for a base currency.

• Geocoding of cities.

• Query current weather and 1 to 7 day forecast.

• Automatic discovery of MCP tools by the client.

• Interactive terminal interface in Spanish.

• Retries on temporary errors when calling OpenAI and network error handling.

Related MCP server: Weather MCP Server

Architecture

Usuario
  |
  v
CLI (main_client.py)
  |
  v
Cliente OpenAI Responses <----> Servidor MCP local (FastMCP)
                                      |
                                      +--> ExchangeRate-API
                                      +--> Open-Meteo

The server is exposed via HTTP transport at http://127.0.0.1:8000/mcp/ by default. The client connects to that URL, loads the five available tools, and delivers their results to the model to generate the final response.

MCP Tools

Requirements

• Python 3.10 or higher.

• An OpenAI API key with access to the Responses API.

• Internet connection to query OpenAI and external APIs.

• An ExchangeRate-API key is optional. Without it, its open endpoint is used.

Installation

Clone the repository and create a virtual environment:

git clone <URL_DEL_REPOSITORIO>
cd <NOMBRE_DEL_REPOSITORIO>
python -m venv .venv

Activate the virtual environment:

# Windows PowerShell
.venv\Scripts\Activate.ps1

# Windows (cmd)
.venv\Scripts\activate.bat

# macOS/Linux
source .venv/bin/activate

Install the dependencies:

python -m pip install -r requirements.txt

Configuration

Copy the example configuration file and fill in the credentials. The .env file is local and should not be included in the repository:

Copy-Item .env.example .env

On macOS or Linux:

cp .env.example .env

The resulting file must contain these variables:

OPENAI_API_KEY=tu_clave_de_openai

# Opcional. Si se deja vacío se usa el endpoint abierto de ExchangeRate-API.
API_KEY_EXCHANGE=

# Opcionales.
MCP_HOST=127.0.0.1
MCP_PORT=8000
OPENAI_MODEL=gpt-4o-mini

OPENAI_API_KEY is required to use the client. Open-Meteo does not require credentials. The application uses a 10-second timeout for external HTTP calls.

Usage

The server and client run in separate terminals. Start the server first:

python main_server.py

In another terminal, with the virtual environment activated, start the client:

python main_client.py

Tests

Unit tests cover currency logic, weather forecast, WMO codes, and error sanitization without calling OpenAI or external APIs:

python -m pip install -r requirements-dev.txt
python -m pytest

Then you can write queries like:

Convierte 100 USD a EUR
¿Cuál es el clima actual en Madrid?
Dame la previsión del tiempo para Nueva York durante 5 días
¿Qué coordenadas tiene Tokio?

Available CLI commands:

Project structure

.
├── .env.example          # Plantilla de configuración local
├── .gitignore            # Archivos excluidos del repositorio
├── client/
│   ├── cli_interface.py    # Interfaz interactiva de terminal
│   └── openai_client.py    # Orquestación OpenAI + MCP
├── config/
│   └── settings.py         # Variables de entorno y endpoints
├── server/
│   ├── api_clients.py      # Clientes HTTP para las APIs externas
│   ├── currency_tools.py   # Herramientas de divisas
│   ├── geocoding_tools.py  # Herramienta de geocodificación
│   ├── mcp_server.py       # Servidor FastMCP y registro de herramientas
│   └── weather_tools.py    # Herramientas meteorológicas
├── main_client.py          # Punto de entrada del cliente
├── main_server.py          # Punto de entrada del servidor
├── requirements.txt        # Dependencias de Python
└── README.md

External APIs

• OpenAI Responses API: query interpretation and tool selection.

• ExchangeRate-API: exchange rates and conversions.

• Open-Meteo: geocoding and weather data.

Results depend on the availability, limits, and terms of use of these services. Using OpenAI may incur costs depending on the account and configured model.