Finanz- und Wetterassistent mit MCP

Kommandozeilenanwendung, die einen lokalen MCP-Server mit der OpenAI Responses API kombiniert. Der Assistent versteht natürlichsprachliche Anfragen, entdeckt die vom Server bereitgestellten Werkzeuge und führt sie aus, um aktuelle Währungs- und Wetterdaten abzufragen.

Das Projekt integriert FastMCP, ExchangeRate-API und Open-Meteo. Es unterstützt auch verkettete Aufrufe: Beispielsweise wird der Name einer Stadt in Koordinaten umgewandelt und dann das aktuelle Wetter oder die Vorhersage abgefragt.

Funktionen

• Umrechnung von Beträgen zwischen Währungen mittels ISO-4217-Codes.

• Abfrage von Wechselkursen für eine Basiswährung.

• Geokodierung von Städten.

• Abfrage des aktuellen Wetters und Vorhersage für 1 bis 7 Tage.

• Automatische Erkennung von MCP-Werkzeugen durch den Client.

• Interaktive Terminal-Oberfläche auf Spanisch.

• Wiederholungsversuche bei temporären Fehlern beim Aufruf von OpenAI und Behandlung von Netzwerkfehlern.

Related MCP server: Weather MCP Server

Architektur

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

Der Server wird standardmäßig über HTTP-Transport unter http://127.0.0.1:8000/mcp/ bereitgestellt. Der Client verbindet sich mit dieser URL, lädt die fünf verfügbaren Werkzeuge und übergibt deren Ergebnisse an das Modell, um die endgültige Antwort zu generieren.

MCP-Werkzeuge

Voraussetzungen

• Python 3.10 oder höher.

• Ein OpenAI-API-Schlüssel mit Zugriff auf die Responses API.

• Internetverbindung zum Abfragen von OpenAI und den externen APIs.

• Ein ExchangeRate-API-Schlüssel ist optional. Ohne ihn wird der offene Endpunkt verwendet.

Installation

Klonen Sie das Repository und erstellen Sie eine virtuelle Umgebung:

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

Aktivieren Sie die virtuelle Umgebung:

# Windows PowerShell
.venv\Scripts\Activate.ps1

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

# macOS/Linux
source .venv/bin/activate

Installieren Sie die Abhängigkeiten:

python -m pip install -r requirements.txt

Konfiguration

Kopieren Sie die Beispielkonfigurationsdatei und füllen Sie die Anmeldeinformationen aus. Die Datei .env ist lokal und sollte nicht in das Repository aufgenommen werden:

Copy-Item .env.example .env

Auf macOS oder Linux:

cp .env.example .env

Die resultierende Datei sollte diese Variablen enthalten:

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 ist erforderlich, um den Client zu verwenden. Open-Meteo benötigt keine Anmeldeinformationen. Die Anwendung verwendet ein Timeout von 10 Sekunden für externe HTTP-Aufrufe.

Verwendung

Der Server und der Client werden in separaten Terminals ausgeführt. Starten Sie zuerst den Server:

python main_server.py

In einem anderen Terminal, mit aktivierter virtueller Umgebung, starten Sie den Client:

python main_client.py

Tests

Die Unit-Tests decken die Währungslogik, Wettervorhersage, WMO-Codes und Fehlerbereinigung ab, ohne OpenAI oder die externen APIs aufzurufen:

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

Danach können Sie Abfragen eingeben wie:

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?

Verfügbare CLI-Befehle:

Projektstruktur

.
├── .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

Externe APIs

• OpenAI Responses API: Interpretation der Abfrage und Werkzeugauswahl.

• ExchangeRate-API: Wechselkurse und Umrechnungen.

• Open-Meteo: Geokodierung und Wetterdaten.

Die Ergebnisse hängen von der Verfügbarkeit, den Limits und Nutzungsbedingungen dieser Dienste ab. Die Nutzung von OpenAI kann je nach Konto und konfiguriertem Modell Kosten verursachen.