Instalación y configuración de FastMCP

Requisitos previos

Antes de instalar FastMCP, asegúrate de tener:

Python 3.10+: FastMCP requiere Python 3.10 o superior.
Administrador de paquetes: Recomendamos usar uv para la mejor experiencia, aunque pip también funciona bien.

Métodos de instalación

Usando uv (Recomendado)

La forma más rápida y fiable de instalar FastMCP:

uv pip install fastmcp

Usando pip

Si prefieres pip:

pip install fastmcp

Instalación para desarrollo

Para trabajos de desarrollo o para obtener las últimas características:

# Clona el repositorio
git clone https://github.com/jlowin/fastmcp.git
cd fastmcp

# Crea y sincroniza el entorno con uv
uv sync

# O usa pip en un entorno virtual
python -m venv venv
source venv/bin/activate  # En Windows: venv\Scripts\activate
pip install -e .

Verificación de la instalación

Prueba tu instalación creando un servidor simple:

# test_install.py
from fastmcp import FastMCP

mcp = FastMCP("Servidor de Prueba")

@mcp.tool
def hello() -> str:
    """Saluda."""
    return "¡Hola desde FastMCP!"

if __name__ == "__main__":
    print("¡FastMCP instalado correctamente!")
    print(f"Nombre del servidor: {mcp.name}")
    # Descomenta para ejecutar el servidor
    # mcp.run()

Ejecuta la prueba:

python test_install.py

Deberías ver:

¡FastMCP instalado correctamente!
Nombre del servidor: Servidor de Prueba

Estructura del proyecto

Para un proyecto FastMCP típico, recomendamos esta estructura:

mi-proyecto-mcp/
├── server.py          # Archivo principal del servidor
├── tools/             # Implementaciones de herramientas
│   ├── __init__.py
│   ├── math_tools.py
│   └── data_tools.py
├── resources/         # Implementaciones de recursos
│   ├── __init__.py
│   └── config.py
├── tests/            # Archivos de prueba
│   └── test_server.py
├── requirements.txt   # Dependencias
└── README.md         # Documentación del proyecto

Configuración del entorno

FastMCP soporta la configuración mediante variables de entorno:

# archivo .env
FASTMCP_LOG_LEVEL=DEBUG
FASTMCP_MASK_ERROR_DETAILS=False
FASTMCP_RESOURCE_PREFIX_FORMAT=path

Variables de entorno comunes:

FASTMCP_LOG_LEVEL: Establece el nivel de registro (DEBUG, INFO, WARNING, ERROR, CRITICAL).
FASTMCP_MASK_ERROR_DETAILS: Oculta información detallada de errores a los clientes.
FASTMCP_RESOURCE_PREFIX_FORMAT: Cómo formatear los prefijos de recursos ("path" o "protocol").

Tu primer servidor FastMCP

Vamos a crear un ejemplo completo de servidor:

# server.py
import random
from datetime import datetime
from fastmcp import FastMCP

# Crea un servidor con configuración
mcp = FastMCP(
    name="Mi Primer Servidor MCP",
    instructions="""
    Este servidor proporciona utilidades básicas, incluyendo:
    - Operaciones matemáticas
    - Generación de números aleatorios
    - Información de la hora actual
    """
)

@mcp.tool
def add_numbers(a: float, b: float) -> float:
    """Suma dos números."""
    return a + b

@mcp.tool
def roll_dice(sides: int = 6, count: int = 1) -> list[int]:
    """Lanza dados con el número de caras especificado."""
    if count > 10:
        raise ValueError("Máximo 10 dados permitidos")
    return [random.randint(1, sides) for _ in range(count)]

@mcp.resource("time://current")
def get_current_time() -> str:
    """Obtiene la fecha y hora actuales."""
    return datetime.now().isoformat()

@mcp.resource("config://server")
def get_server_config() -> dict:
    """Obtiene la información de configuración del servidor."""
    return {
        "name": mcp.name,
        "version": "1.0.0",
        "features": ["tools", "resources"],
        "uptime": "Acaba de iniciar"
    }

if __name__ == "__main__":
    print(f"Iniciando {mcp.name}...")
    mcp.run()

Ejecutando tu servidor

Modo STDIO (predeterminado)

Perfecto para desarrollo local y herramientas de línea de comandos:

python server.py

Modo HTTP

Mejor para clientes basados en la web y pruebas de desarrollo:

# En tu server.py
if __name__ == "__main__":
    mcp.run(transport="http", host="127.0.0.1", port=8000)

Luego ejecuta:

python server.py

Tu servidor estará disponible en http://127.0.0.1:8000/mcp/

Probando tu instalación

Crea un cliente de prueba simple para verificar que todo funciona:

# test_client.py
import asyncio
from fastmcp import Client

async def test_server():
    # Prueba vía HTTP (si se ejecuta en modo HTTP)
    async with Client("http://localhost:8000/mcp/") as client:
        # Lista las herramientas disponibles
        tools = await client.list_tools()
        print("Herramientas disponibles:", [tool.name for tool in tools])

        # Llama a una herramienta
        result = await client.call_tool("add_numbers", {"a": 5, "b": 3})
        print("5 + 3 =", result.text)

        # Lee un recurso
        time_resource = await client.read_resource("time://current")
        print("Hora actual:", time_resource.content)

if __name__ == "__main__":
    asyncio.run(test_server())

Problemas comunes de instalación

ImportError: No module named 'fastmcp'

Asegúrate de que FastMCP esté instalado en el entorno de Python correcto:

# Verifica qué Python estás usando
which python
python --version

# Instala en el entorno correcto
python -m pip install fastmcp

Conflictos de versión

Si actualizas desde FastMCP 1.0 o el SDK oficial de MCP:

# Desinstala las versiones antiguas primero
pip uninstall mcp fastmcp

# Instala la última versión
pip install fastmcp

Errores de permiso

En algunos sistemas, podrías necesitar:

# Usa la bandera --user
pip install --user fastmcp

# O usa uv, que maneja esto mejor
uv pip install fastmcp

Próximos pasos

Ahora que FastMCP está instalado y en funcionamiento, estás listo para:

Crear Herramientas: Aprende a crear potentes herramientas MCP.
Añadir Recursos: Expón fuentes de datos a tus clientes LLM.
Conectarse a Claude Code: Integrar con entornos de desarrollo.
Desplegar en Producción: Escala tus servidores para uso en entornos reales.

En la siguiente sección, profundizaremos en la creación de herramientas sofisticadas que pueden manejar operaciones complejas y procesamiento de datos.