Gradio-MCP-Server-Guide: Build, Test, Deploy & Integrate

Das Model Context Protocol (MCP) ist ein offener Standard, um KI-Modelle mit externen Tools, APIs und Datenquellen zu verbinden. Es bietet eine einheitliche Methode, damit Large Language Models (LLMs) mit externen Systemen interagieren.

Während die Welt auf agentische Workflows zusteuert, in denen KI-Systeme als autonome Agenten handeln, wird MCP immer relevanter. Das Gradio-Ökosystem bietet den einfachsten und effizientesten Weg, MCP-Server zu bauen – so entwickelst du mit minimalem Aufwand leistungsfähige KI-Tools.

In diesem Tutorial werden wir:

1. Lokal einen einfachen Gradio-MCP-Server einrichten und testen.
2. Einen produktionsreifen MCP-Server mit mehreren Tools entwickeln.
3. Ihn auf Hugging Face Spaces bereitstellen.
4. Ihn mit Cursor AI und Claude Desktop testen.

Wenn du Designing Agentic Systems with LangChain praxisnah ausprobieren willst, schau dir unseren Kurs an.

Erste Schritte mit Gradio MCP

Die aktuelle Gradio-Version (5.32.0) unterstützt MCP nativ. Damit wird das Erstellen und Ausführen von MCP-Servern extrem einfach. Du musst die MCP-Unterstützung nur per Code-Argument oder Umgebungsvariable aktivieren.

Gradio-MCP-Server nutzen das Server-Sent-Events-Protokoll (SSE) für Echtzeit-Einwegkommunikation vom Server zum Client – ideal, um LLM-Antworten zu streamen.

1. Installiere die neueste Gradio-Version mit MCP-Unterstützung.

pip install -U "gradio[mcp]"

2. Erstelle eine Gradio-App, die einen Stadtnamen entgegennimmt und Wetterdaten zurückgibt (hier Mock-Daten). Ein idealer Einstieg – vor allem, wenn du Gradio schon kennst.

import gradio as gr


def check_weather(city):
    """
    Simple weather checker function (mock data for demonstration).

    Args:
        city (str): The city name to check weather for

    Returns:
        str: Weather information for the city
    """
    # Mock weather data for demonstration
    weather_data = {
        "london": "Cloudy, 15°C",
        "paris": "Sunny, 22°C",
        "tokyo": "Rainy, 18°C",
        "new york": "Partly cloudy, 20°C",
        "sydney": "Sunny, 25°C",
    }

    city_lower = city.lower().strip()

    if city_lower in weather_data:
        return f"Weather in {city.title()}: {weather_data[city_lower]}"
    else:
        return f"Weather data not available for {city}. Try: London, Paris, Tokyo, New York, or Sydney"


demo = gr.Interface(
    fn=check_weather,
    inputs=[gr.Textbox("London", label="Enter city name")],
    outputs=[gr.Textbox(label="Weather Info")],
    title="Simple Weather Checker",
    description="Enter a city name to check the weather (demo with mock data).",
)

if __name__ == "__main__":
    demo.launch(mcp_server=True)

3. Es gibt zwei Möglichkeiten, MCP in Gradio zu aktivieren:

• Über das mcp_server-Argument: demo.launch(mcp_server=True)
• Über eine Umgebungsvariable: export GRADIO_MCP_SERVER=True

4. Speichere die Python-Datei test.py und führe sie aus.

$ python test.py                                            
* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse

In der Terminalausgabe erscheinen zwei URLs:

• App-URL: http://127.0.0.1:7860 (öffnet die Gradio-App im Browser).
• MCP-Server-URL: http://127.0.0.1:7860/gradio_api/mcp/sse (für MCP-kompatible Clients).

5. Öffne die App-URL (http://127.0.0.1:7860) im Browser. Gib eine Stadt ein (z. B. Tokyo) und prüfe das Wetter.

6. Klicke unten in der App auf die Schaltfläche „Use via API or MCP“. Daraufhin werden zusätzliche Informationen zur API und zum MCP-Server deiner App angezeigt.

7. Um den MCP-Server mit Cursor AI zu testen, öffne die Cursor-Einstellungen, wechsle zum Tab „MCP“ und klicke auf „+ Add new global MCP server“.

8. Füge die folgende JSON-Konfiguration zur MCP-Konfigurationsdatei hinzu:

{
  "mcpServers": {
    "gradio": {
      "url": "http://127.0.0.1:7860/gradio_api/mcp/sse"
    }
  }
}

9. Speichere die Datei. Du siehst nun einen aktiven MCP-Server namens gradio mit dem Tool check_weather.

Zum Testen dieses MCP-Servers erstellen wir in Cursor einen neuen Chat im Agent-Modus (CTRL + T) und fragen nach dem Wetter in Tokyo. Cursor bittet um Erlaubnis, das MCP-Tool auszuführen. Bestätige dies.

Daraufhin ruft der MCP-Server die Wetterdaten ab und gibt das Ergebnis zurück:

Einen Multi-Tool-MCP-Server mit Gradio bauen

Lass uns etwas Praktisches und Produktionsreifes bauen. In diesem Projekt erstellen wir einen Multi-Tool-MCP-Server mit Gradio.

Der Server enthält zwei Tools:

1. Live-Wetter-Tool: Ruft aktuelle Wetterdaten über die Tavily-API ab.
2. Stadt-News-Tool: Liefert die 5 neuesten Schlagzeilen zu einer Stadt über die Tavily-API.

So unterstützt der Server Reisende mit Wetter-Updates und relevanten Nachrichten.

Wir richten den MCP-Server ein, testen ihn lokal, stellen ihn auf Hugging Face Spaces bereit und prüfen den Live-Server mit Cursor AI und Claude Desktop.

1. Setup

Erstelle einen neuen Space unter https://huggingface.co/new-space, vergib einen App-Namen, füge eine Kurzbeschreibung hinzu und wähle Gradio als Template.

Quelle: new-space

Nach dem Anlegen wirst du in deinen neuen Space weitergeleitet. Folge den Anweisungen zur Einrichtung.

Klonen des Repositorys in dein lokales Projektverzeichnis

git clone https://huggingface.co/spaces/kingabzpro/live-city-mcp

Für dieses Projekt nutzen wir die Tavily-API für Websuche. Lege ein Konto bei Tavily AI an und generiere einen API-Schlüssel.

Quelle: Tavily AI

Speichere den API-Schlüssel anschließend als Umgebungsvariable auf deinem System

TAVILY_API_KEY="API-KEY"

Installiere danach das Tavily-Python-SDK

pip install tavily-python

2. Den MCP-Server erstellen

Dieser MCP-Server bietet zwei Tools, die beide die Tavily-API nutzen, um aktuelle Webinformationen abzurufen. Das erste Tool nimmt einen Stadtnamen und erstellt einen detaillierten Wetterbericht, das zweite listet zu derselben Stadt die Schlagzeilen der fünf wichtigsten Nachrichten. Wir bauen jeweils eine grafische Oberfläche und kombinieren sie anschließend in einer Tab-Ansicht.

app.py:

import gradio as gr
from tavily import TavilyClient


def get_city_weather_info(city_name):
    """
    Search for current weather information about a city using Tavily search API

    Args:
        city_name (str): Name of the city
        api_key (str): Your Tavily API key

    Returns:
        dict: Search results containing weather information
    """
    # Initialize Tavily client
    client = TavilyClient()

    # Search for current weather information
    search_query = f"current weather in {city_name} temperature humidity conditions"

    try:
        # Perform the search
        response = client.search(
            query=search_query, search_depth="basic", max_results=5
        )

        # Extract relevant information from search results
        weather_info = {"city": city_name, "search_query": search_query, "results": []}

        # Process each search result
        for result in response.get("results", []):
            weather_info["results"].append(
                {
                    "title": result.get("title", ""),
                    "content": result.get("content", ""),
                    "url": result.get("url", ""),
                }
            )

        # Add the answer if available
        if "answer" in response:
            weather_info["summary"] = response["answer"]

        return weather_info

    except Exception as e:
        return {
            "city": city_name,
            "error": f"Failed to fetch weather information: {str(e)}",
        }


def get_city_news(city_name):
    """
    Fetches the top 5 news articles for a given city using the Tavily API.

    Args:
        city_name (str): Name of the city

    Returns:
        dict: News results containing the top 5 articles or an error message
    """
    # Initialize Tavily client
    client = TavilyClient()

    # Search query for news about the city
    search_query = f"Top 5 latest news articles about {city_name}, including major events, politics, economy, and local updates."

    try:
        # Perform the search
        response = client.search(
            query=search_query,
            search_depth="advanced",
            max_results=5,
        )

        # Extract relevant information from search results
        news_info = {"city": city_name, "search_query": search_query, "articles": []}

        # Process each search result
        for result in response.get("results", []):
            news_info["articles"].append(
                {
                    "title": result.get("title", ""),
                    "content": result.get("content", ""),
                    "url": result.get("url", ""),
                }
            )

        # Add the answer if available
        if "answer" in response:
            news_info["summary"] = response["answer"]

        return news_info

    except Exception as e:
        return {"city": city_name, "error": f"Failed to fetch news: {str(e)}"}


# Create Gradio interfaces
weather_demo = gr.Interface(
    fn=get_city_weather_info,
    inputs=gr.Textbox(label="Enter City Name", placeholder="e.g., New York"),
    outputs=gr.JSON(label="Weather Information"),
    description="Get current weather details for a city.",
)

news_demo = gr.Interface(
    fn=get_city_news,
    inputs=gr.Textbox(label="Enter City Name", placeholder="e.g., London"),
    outputs=gr.JSON(label="News Articles"),
    description="Get the latest news articles for a city.",
)

# Create tabbed interface
demo = gr.TabbedInterface(
    [weather_demo, news_demo], ["Weather", "News"], title="City Information Hub"
)

if __name__ == "__main__":
    # Launch without MCP server to avoid initialization issues
    demo.launch(share=False, mcp_server=True, debug=True)

3. Den MCP-Server lokal testen

Bevor wir bereitstellen, testen wir den MCP-Server lokal. Starte den Server mit folgendem Terminalbefehl:

python app.py

Ausgabe:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

🔨 MCP server (using SSE) running at: http://127.0.0.1:7860/gradio_api/mcp/sse

Öffne http://127.0.0.1:7860 im Browser und gib im Eingabefeld eine Stadt ein. Der Server liefert detaillierte Wetterinformationen im JSON-Format.

Die Anwendung sollte ohne Probleme laufen und für die eingegebene Stadt korrekte Wetter- und Nachrichtendaten liefern.

4. Den MCP-Server auf Hugging Face Spaces bereitstellen

So stellst du den Server bereit:

1. Erstelle die Datei requirements.txt und füge die folgende Abhängigkeit hinzu:

tavily-python==0.7.3

2. Committe die Änderungen und pushe sie in den Hugging-Face-Space.

git add .                                                                                                
live-city-mcp  git commit -m "weather and news MCP"                                                                     
git push  

Nach dem Push startet der Build des Hugging-Face-Spaces.

Quelle: Live City Mcp

Nach etwa einer Minute ist der MCP-Server live erreichbar unter Live City Mcp.

Quelle: Live City Mcp

3. Bevor wir ihn als MCP-Server verwenden, müssen wir die Umgebungsvariable mit dem Tavily-Access-Token setzen. Öffne hierzu die Space-Einstellungen, scrolle nach unten und klicke auf „New Secret“. Füge dann den API-Key und den Tavily-API-Namen hinzu.

Quelle: live-city-mcp/settings

5. Den bereitgestellten MCP-Server mit Cursor AI testen

Unser MCP ist bereitgestellt und läuft einwandfrei. Jetzt richten wir den MCP-Client ein. Zuerst konfigurieren wir Cursor AI. Gehe in die Cursor-Einstellungen, öffne den MCP-Tab und klicke auf „+Add new global MCP server“. Trage folgenden Code ein:

{
  "mcpServers": {
    "weather-news": {
      "url": "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse"
    }
  }
}

Du siehst, dass der MCP weather-news mit zwei Tools läuft. Stellen wir eine Frage zum Wetter in Islamabad.

Wie zu sehen ist, kam die Antwort schnell und präzise.

Zur Verifizierung können wir online suchen und das Wetter bei AccuWeather prüfen.

Quelle: AccuWeather

Als Nächstes testen wir das zweite Tool und fragen nach Nachrichten rund um Islamabad.

Ergebnis: eine Liste mit vier Schlagzeilen zu Pakistan. Wenn die Tavily-API keine aktuellen Nachrichten speziell zu Islamabad findet, wechselt sie auf Länderebene.

6. Den bereitgestellten MCP-Server mit Claude Desktop testen

Richte Claude Desktop ein: Öffne die Einstellungen, klicke auf „Developer“ und dann auf „Edit Config“. Dadurch gelangst du in den Ordner, in dem du die Datei claude_desktop_config.json bearbeiten musst.

Claude Desktop unterstützt derzeit keine SSE-basierten MCP-Server. In diesem Fall kannst du das Tool mcp-remote verwenden.

Um mcp-remote auszuführen, installiere zunächst Node.js über die Seite Download Node.js®. Füge dann den folgenden Code in deine Datei claude_desktop_config.json ein:

 "Live City MCP": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://kingabzpro-live-city-mcp.hf.space/gradio_api/mcp/sse",
        "--transport",
        "sse-only"
      ]
    }

So könnte die MCP-Serverkonfiguration aussehen.

Beende anschließend die Claude-Desktop-App und starte sie neu. Du siehst nun Zugriff auf den neuen MCP-Server „Live City MCP“ mit zwei verfügbaren Tools.

Ich reise bald nach Irland und habe nach dem Wetter in Dublin gefragt – die Ergebnisse waren sehr gut.

Am komfortabelsten greifst du über Claude Desktop auf den MCP-Server zu. Die Nutzung ist interaktiv, unterstützt Tools optimal und präsentiert Informationen übersichtlich.

Fazit

Wenn du bereits Gradio-Apps für Machine-Learning-Projekte erstellst, war es noch nie so einfach, deine App in einen MCP-Server zu verwandeln. Mit nur einem Argument (mcp_server=True) kann deine Gradio-App auch als MCP-Server fungieren – für nahtlose Integrationen mit Tools wie Cursor AI und Claude Desktop. So eröffnen sich spannende Möglichkeiten, KI-Anwendungen mit externen Systemen und Workflows zu verbinden.

In diesem praxisnahen Tutorial haben wir die Grundlagen von Gradio MCP erkundet, einen MCP-Server gebaut und getestet und ein Projekt mit der Tavily-API umgesetzt, um Live-Wetterdaten und Stadtnachrichten abzurufen. Zum Schluss haben wir das Projekt auf Hugging Face Spaces bereitgestellt und mit gängigen MCP-kompatiblen Clients getestet.

Wenn du tiefer in agentische KI und die hier behandelten Konzepte eintauchen willst, empfehlen wir diese Ressourcen:

• Understanding AI Agents: The Future of Autonomous Systems
• Claude Code: A Guide With Practical Examples
• Working with Hugging Face | Your Guide to the Hub Course
• Build dynamic LangChain agents Course
• Chrome DevTools MCP: AI-Powered Browser Automation and Debugging