mcp_training

MCP-Server mit Werkzeugen für Wetter, Geokodierung und Währungen sowie ein Konsolen-Client, der mit einem OpenAI-Modell spricht, das diese Werkzeuge nutzen kann.

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

Wie es funktioniert

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

Der Client führt die Werkzeuge nicht aus: Er übergibt OpenAI die öffentliche URL des MCP-Servers, und OpenAI listet sie auf, ruft sie auf und verknüpft sie (Stadt → Koordinaten → Wetter). Deshalb muss der Server über das Internet erreichbar sein: OpenAI verbindet sich von seinen Servern aus, nicht von deinem Rechner.

Werkzeuge

Wetter und Geokodierung nutzen Open-Meteo (kostenlos, kein Schlüssel). Währungen nutzen ExchangeRate-API, die einen Schlüssel erfordert, und unterstützen 20 Währungen (/monedas in der CLI).

Struktur

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

Installation

Erfordert Python 3.11+. Mit uv (empfohlen):

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

Oder mit pip und einer virtuellen Umgebung:

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

Konfiguration

Kopiere das Beispiel und fülle deine Schlüssel aus:

cp .env.example .env

Nur zwei Variablen sind erforderlich:

Und eine dritte, MCP_PUBLIC_URL, die im nächsten Schritt ausgefüllt wird. Alles andere (Modell, Port, Transport, Timeouts, Log-Level) hat sinnvolle Standardwerte und ist in .env.example dokumentiert.

Verwendung

Es werden drei Terminals benötigt: Server, Tunnel und Client.

1. Starte den MCP-Server

uv run python main_server.py

Er lauscht auf http://127.0.0.1:8002/mcp.

2. Veröffentliche den Server mit einem Tunnel

OpenAI benötigt eine öffentliche URL, um den Server zu erreichen. Mit devtunnel:

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

Kopiere die ausgegebene URL (https://xxxxxxx-8002.euw.devtunnels.ms) und setze sie in die .env:

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

Jeder Tunnel ist geeignet (ngrok, Cloudflare Tunnel …); wichtig ist nur, dass die URL von außen erreichbar ist. Der Client hängt /mcp selbst an, falls es nicht enthalten ist.

3. Starte den Client

uv run python main_client.py

Gib deine Anfrage ein und drücke die Eingabetaste. Die Konversation hat ein Gedächtnis: Nachdem du nach Madrid gefragt hast, kannst du einfach «und morgen?» sagen.

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

CLI-Befehle:

Den Server ohne den Client verwenden

Der Server ist ein Standard-MCP-Server: Er funktioniert mit jedem kompatiblen Client. Um ihn als Unterprozess zu verbinden (Claude Desktop, Claude Code …), setze MCP_TRANSPORT=stdio in der .env; dann werden weder Tunnel noch Port benötigt.

Häufige Probleme

Um die Details jedes Aufrufs (Argumente, Antworten, URLs) zu sehen, setze LOG_LEVEL=DEBUG in der .env. Die Logs gehen nach stderr, also speichert python main_client.py > chat.txt nur die Konversation.