MCP Utils

Un paquete de Python con utilidades y ayudantes para construir servidores compatibles con MCP, que a menudo utiliza Flask y Redis.

GitHub
5

Documentación

mcp-utils

Un paquete de utilidades de Python para construir servidores del Model Context Protocol (MCP).

Tests PyPI - Version

Tabla de Contenidos

Descripción General

mcp-utils proporciona utilidades y ayudas para construir servidores compatibles con MCP en Python, con un enfoque en implementaciones síncronas usando Flask. Este paquete está diseñado para desarrolladores que quieren implementar servidores MCP en sus aplicaciones Python existentes sin la complejidad del código asíncrono.

Características Principales

  • Utilidades básicas para la implementación de servidores MCP
  • Soporte para Server-Sent Events (SSE)
  • Decoradores simples para endpoints MCP
  • Implementación síncrona
  • Soporte del protocolo HTTP
  • Cola de respuestas con Redis
  • Modelos Pydantic completos para el esquema MCP
  • Validación y documentación integradas

Instalación

pip install mcp-utils

Requisitos

  • Python 3.10+
  • Pydantic 2

Dependencias Opcionales

  • Flask (para el servidor web)
  • Gunicorn (para despliegue en producción)
  • Redis (para la cola de respuestas)

Uso

Servidor MCP Básico

Aquí hay un ejemplo sencillo de cómo crear un servidor MCP:

from mcp_utils.core import MCPServer
from mcp_utils.schema import GetPromptResult, Message, TextContent, CallToolResult

# Create a basic MCP server
mcp = MCPServer("example", "1.0")

@mcp.prompt()
def get_weather_prompt(city: str) -> GetPromptResult:
    return GetPromptResult(
        description="Weather prompt",
        messages=[
            Message(
                role="user",
                content=TextContent(
                    text=f"What is the weather like in {city}?",
                ),
            )
        ],
    )

@mcp.tool()
def get_weather(city: str) -> str:
    return "sunny"

Ejemplo con Flask

Para uso en producción, puedes usar una aplicación Flask simple con el servidor MCP y soporte para Streamable HTTP desde la versión 2025-06-18.

from flask import Flask, Response, url_for, request

# Create Flask app and MCP server with Redis queue
app = Flask(__name__)
mcp = MCPServer(
    "example",
    "1.0",
)

@app.route("/mcp", methods=["POST"])
def mcp_route():
    response = mcp.handle_message(request.get_json())
    return jsonify(response.model_dump(exclude_none=True))


if __name__ == "__main__":
    app.run(debug=True)

Ejemplo de Manejo de Transacciones con SQLAlchemy

Para uso en producción, puedes integrar el servidor MCP con Flask, Redis y SQLAlchemy para un mejor manejo de mensajes y gestión de transacciones de base de datos:

from flask import Flask, request
from sqlalchemy.orm import Session
from sqlalchemy import create_engine

# Create engine for PostgreSQL database
engine = create_engine("postgresql://user:pass@localhost/dbname")

# Create Flask app and MCP server with Redis queue
app = Flask(__name__)
mcp = MCPServer(
    "example",
    "1.0",
)

@app.route("/mcp", methods=["POST"])
def mcp_route():
    with Session(engine) as session:
        try:
            response = mcp.handle_message(request.get_json())
            session.commit()
        except:
            session.rollback()
            raise
        else:
            return jsonify(response.model_dump(exclude_none=True))


if __name__ == "__main__":
    app.run(debug=True)

Para un ejemplo más completo que incluya configuración de registro y gestión de sesiones, consulta la aplicación Flask de ejemplo en el repositorio.

Ejecución con Gunicorn

Gunicorn es un mejor enfoque incluso para ejecutar localmente. Para ejecutar la aplicación con gunicorn

from gunicorn.app.base import BaseApplication

class FlaskApplication(BaseApplication):
    def __init__(self, app, options=None):
        self.options = options or {}
        self.application = app
        super().__init__()

    def load_config(self):
        config = {
            key: value
            for key, value in self.options.items()
            if key in self.cfg.settings
        }
        for key, value in config.items():
            self.cfg.set(key.lower(), value)

    def load(self):
        return self.application


if __name__ == "__main__":
    handler = logging.StreamHandler(sys.stdout)
    formatter = logging.Formatter("[%(asctime)s] [%(levelname)s] %(name)s: %(message)s")
    handler.setFormatter(formatter)
    logger.addHandler(handler)
    options = {
        "bind": "0.0.0.0:9000",
        "workers": 1,
        "worker_class": "gevent",
        "loglevel": "debug",
    }
    FlaskApplication(app, options).run()

Conexión con Clientes MCP

Cursor

  • Edita la configuración de MCP y añade a la configuración
{
  "mcpServers": {
    "server-name": {
      "url": "http://localhost:9000/mcp"
    }
  }
}

Claude Desktop

Al momento de escribir esto, Claude Desktop no soporta MCP a través de SSE y solo soporta stdio. Para conectar Claude Desktop con un servidor MCP, necesitarás usar mcp-proxy.

Ejemplo de configuración para Claude Desktop:

{
  "mcpServers": {
    "weather": {
      "command": "/Users/yourname/.local/bin/mcp-proxy",
      "args": ["http://127.0.0.1:9000/sse"]
    }
  }
}

Instalación mediante Smithery

Para instalar MCP Proxy para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install mcp-proxy --client claude

Instalación mediante PyPI

La versión estable del paquete está disponible en el repositorio de PyPI. Puedes instalarlo usando el siguiente comando:

# Option 1: With uv (recommended)
uv tool install mcp-proxy

# Option 2: With pipx (alternative)
pipx install mcp-proxy

Una vez instalado, puedes ejecutar el servidor usando el comando mcp-proxy.

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar un Pull Request.

Proyectos Relacionados

  • MCP Python SDK - El SDK oficial asíncrono de Python para MCP
  • mcp-proxy - Una herramienta proxy para conectar Claude Desktop con servidores MCP

Licencia

Licencia MIT

Pruebas con MCP Inspector

El MCP Inspector es una herramienta útil para probar y depurar servidores MCP. Proporciona una interfaz web para inspeccionar y probar los endpoints del servidor MCP.

Instalación

Instala MCP Inspector usando npm:

npm install -g @modelcontextprotocol/inspector

Uso

  1. Inicia tu servidor MCP (por ejemplo, el ejemplo de Flask anterior)
  2. Ejecuta MCP Inspector:
git clone git@github.com:modelcontextprotocol/inspector.git
cd inspector
npm run build
npm start
  1. Abre tu navegador y navega a http://127.0.0.1:6274/
  2. Ingresa la URL de tu servidor MCP (por ejemplo, http://localhost:9000/sse)
  3. Usa el inspector para:
    • Cambiar el tipo de transporte a SSE
    • Probar conexiones del servidor
    • Monitorear eventos SSE
    • Enviar mensajes de prueba
    • Depurar respuestas

Esta herramienta es particularmente útil durante el desarrollo para asegurar que tu implementación del servidor MCP funcione correctamente y cumpla con la especificación del protocolo.