Desarrolla tu primer Servidor MCP (Model Context Protocol) con FastMCP y Python

En este tutorial desarrollaremos un ejemplo práctico y completo en Python utilizando FastMCP (del ecosistema de Prefect / MCP) para crear un servidor MCP que consulte una API REST externa en tiempo real. En este ejemplo consultaremos la API pública de Open-Meteo para obtener la temperatura y el clima de cualquier ciudad sin necesidad de claves de API.

Antes de inicar con el desarrolla validamos la estructura de la API Open-Meteo con el nombre de la cuidad de Lima:

1. Instalación de dependencias

Primero, instala fastmcp e httpx (para realizar peticiones HTTP asíncronas):

pip install fastmcp httpx

2. Código del Servidor (server.py)

Crea un archivo llamado server.py:

import httpx
from fastmcp import FastMCP

# 1. Inicializamos el servidor FastMCP con un nombre descriptivo
mcp = FastMCP("Servidor Clima Externo")


# 2. Definimos una herramienta (Tool) usando el decorador @mcp.tool()
@mcp.tool()
async def obtener_clima(ciudad: str) -> str:
    """Obtiene la temperatura y condiciones meteorológicas actuales de una ciudad en tiempo real.

    Args:
        ciudad: Nombre de la ciudad a consultar (ej. 'Lima', 'Madrid', 'Mexico City').
    """
    async with httpx.AsyncClient() as client:
        # Paso A: Obtener las coordenadas geográficas de la ciudad
        geo_url = f"https://geocoding-api.open-meteo.com/v1/search?name={ciudad}&count=1&language=es&format=json"
        geo_response = await client.get(geo_url)
        geo_data = geo_response.json()

        if not geo_data.get("results"):
            return f"Error: No se encontraron coordenadas para la ciudad '{ciudad}'."

        lugar = geo_data["results"][0]
        lat, lon = lugar["latitude"], lugar["longitude"]
        nombre_completo = (
            f"{lugar.get('name')}, {lugar.get('country', 'Desconocido')}"
        )

        # Paso B: Consultar la API de clima usando las coordenadas
        clima_url = f"https://api.open-meteo.com/v1/forecast?latitude={lat}&longitude={lon}&current_weather=true"
        clima_response = await client.get(clima_url)
        clima_data = clima_response.json()

        if "current_weather" not in clima_data:
            return f"Error: No se pudo obtener el clima para {nombre_completo}."

        actual = clima_data["current_weather"]
        temp = actual.get("temperature")
        viento = actual.get("windspeed")

        return f"El clima actual en {nombre_completo} es de {temp}°C con un viento de {viento} km/h."


# 3. Punto de entrada para ejecutar el servidor MCP
if __name__ == "__main__":
    mcp.run()

3. ¿Cómo funciona este código?

• Inferencia de Tipo y Documentación: FastMCP utiliza los type hints de Python (ciudad: str) y el docstring de la función para generar automáticamente el esquema JSON Schema que el cliente IA (como Claude Desktop) leerá para entender cuándo y cómo usar esta herramienta.
• Asincronía con httpx: Al definir la función con async def, el servidor MCP puede atender múltiples consultas de la IA sin bloquear el hilo principal mientras espera la respuesta de la API externa.
• Protocolo Automático: La llamada mcp.run() inicia el transporte por defecto (STDIO), permitiendo que cualquier cliente MCP ejecute este script en segundo plano y consuma la función obtener_clima.

4. ¿Cómo probar la interfaz gráfica de FastMCP?

Con el comando npx -y @modelcontextprotocol/inspector python server.py se ejecutará el inspector MCP en el explorador.

npx -y @modelcontextprotocol/inspector python server.py

Recuerda tener Node.js/npx instalado para ejecutar FastMCP la última versión oficial del MCP Inspector.

La url Sandbox (MCP Apps: http://localhost:[puerto]/..) abrirá un entorno de pruebas visual en tu navegador donde podrás escribir nombres de ciudades y probar la ejecución en tiempo real en el servidor MCP.

• Desde el MCP Inspector clic en el Disconnected para validar habilitar el Servidor Clima Externo.

• Desde el el Servidor Clima Externo clic en tag Tools para validar la herramienta obtener_clima.

• Desde el tag Tools selecciona la herramienta obtener_clima, seguidamente ingresa el nombre de la cuidad París.

Resultado de la búsqueda será en formato JSON

Resumen

• Código Python del Servidor de Clima (server.py) Utiliza la librería FastMCP y httpx para crear un servidor que expone una herramienta (Tool) asíncrona llamada obtener_clima. Su función es recibir el nombre de una ciudad, consultar de forma gratuita y en tiempo real la API geespacial y de pronósticos de Open-Meteo, y devolver las condiciones meteorológicas actuales (temperatura y viento) con un formato amigable para el modelo de lenguaje.
• Qué cumple y hace FastMCP FastMCP es un framework de alto nivel diseñado para simplificar la creación de servidores bajo el estándar Model Context Protocol (MCP). Funciona de manera similar a FastAPI: utiliza decoradores (@mcp.tool()) y los type hints nativos de Python para convertir cualquier función estándar en una herramienta ejecutable por una IA. Automatiza la validación de esquemas (con Pydantic), gestiona los protocolos de comunicación por debajo y permite levantar entornos de desarrollo o conectarse con clientes de IA (como Claude) sin lidiar con los detalles complejos del protocolo JSON-RPC.
• Propósito del comando npx -y @modelcontextprotocol/inspector python server.py este comando descarga temporalmente (sin necesidad de instalación permanente) y ejecuta el MCP Inspector oficial de la comunidad. Su objetivo es levantar una interfaz gráfica de desarrollo web local que ejecuta automáticamente tu script de Python (server.py) mediante transporte stdio. Permite inspeccionar, probar manualmente y validar las herramientas y recursos expuestos por tu servidor antes de integrarlo en clientes finales como Claude Desktop.