Cómo crear tu primer Plugin MCP en Python en 10 minutos

¿Qué es un Plugin MCP y por qué te interesa?

Los Plugins MCP (Model Context Protocol) son la pieza que falta para que tus asistentes de IA dejen de ser "cajas negras" y empiecen a interactuar con el mundo real. Básicamente, un Plugin MCP es un servidor ligero que expone herramientas, recursos y prompts a cualquier cliente que hable el protocolo MCP. Piensa en él como un puente: tu asistente de código, tu chat local o incluso un script personalizado pueden llamar a funciones de Python reales, consultar bases de datos, ejecutar cálculos complejos o interactuar con APIs externas, todo desde una conversación.

La gracia está en que no necesitas ser un gurú de la arquitectura de software. Con unos pocos conceptos y una estructura clara, puedes tener tu primer plugin funcional en menos de 10 minutos. En este artículo te voy a guiar paso a paso para que construyas un plugin que ejecute herramientas útiles, y al final te llevarás un prompt listo para usar.

Paso 1: Prepara tu entorno y estructura base

Antes de escribir código, asegúrate de tener Python 3.10+ y pip actualizados. Crea una carpeta para tu proyecto, por ejemplo mi_primer_mcp, y dentro de ella un archivo requirements.txt con el siguiente contenido:

requirements.txtmcp>=1.0.0 httpx Ejecuta en tu terminal: pip install -r requirements.txt. Esto instalará la librería oficial MCP de Python y la librería httpx para hacer peticiones HTTP si las necesitas.

Ahora crea el archivo principal, por ejemplo server.py. La estructura mínima de un servidor MCP es un script que importa el servidor, define herramientas y se ejecuta. Escribe esto:

server.pyfrom mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import asyncio 1. Creamos la instancia del servidor MCP app = Server("mi_primer_plugin") 2. Definimos una herramienta simple @app.list_tools() async def list_tools() -> list[Tool]: return [ Tool( name="saludar", description="Saluda a una persona por su nombre", inputSchema={ "type": "object", "properties": { "nombre": { "type": "string", "description": "Nombre de la persona a saludar" } }, "required": ["nombre"] } ) ] 3. Implementamos la lógica de la herramienta @app.call_tool() async def call_tool(name: str, arguments: dict) -> list[TextContent]: if name == "saludar": nombre = arguments["nombre"] mensaje = f"¡Hola {nombre}! Este es tu primer plugin MCP funcionando." return [TextContent(type="text", text=mensaje)] raise ValueError(f"Herramienta desconocida: {name}") 4. Arrancamos el servidor async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, app.create_initialization_options()) if __name__ == "__main__": asyncio.run(main()) Este código ya es funcional. Define un servidor que expone una herramienta llamada "saludar" que recibe un nombre y devuelve un saludo personalizado. El servidor se comunica a través de la entrada/salida estándar (stdio), que es el método más común para integrar plugins MCP con asistentes como Claude Desktop o cualquier cliente que soporte el protocolo.

Paso 2: Añade funcionalidades reales (herramientas útiles)

Un saludo está bien, pero lo potente es que tu plugin haga cosas que la IA por sí sola no puede. Vamos a añadir dos herramientas más: una que calcule el precio con IVA y otra que obtenga el clima actual de una ciudad usando una API pública. Modifica tu archivo server.py para que quede así:

server.py (ampliado)from mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import asyncio import httpx app = Server("plugin_utilidades") --- Herramienta 1: Calcular precio con IVA --- @app.list_tools() async def list_tools() -> list[Tool]: return [ Tool( name="calcular_iva", description="Calcula el precio final de un producto aplicando un porcentaje de IVA", inputSchema={ "type": "object", "properties": { "precio_base": { "type": "number", "description": "Precio sin IVA" }, "porcentaje_iva": { "type": "number", "description": "Porcentaje de IVA (ej: 21 para 21%)", "default": 21 } }, "required": ["precio_base"] } ), Tool( name="obtener_clima", description="Obtiene el clima actual de una ciudad usando wttr.in", inputSchema={ "type": "object", "properties": { "ciudad": { "type": "string", "description": "Nombre de la ciudad" } }, "required": ["ciudad"] } ) ] @app.call_tool() async def call_tool(name: str, arguments: dict) -> list[TextContent]: if name == "calcular_iva": precio_base = arguments["precio_base"] iva = arguments.get("porcentaje_iva", 21) precio_final = precio_base * (1 + iva / 100) resultado = ( f"Precio base: {precio_base:.2f} €\n" f"IVA aplicado: {iva}%\n" f"Precio final: {precio_final:.2f} €" ) return [TextContent(type="text", text=resultado)] elif name == "obtener_clima": ciudad = arguments["ciudad"] url = f"https://wttr.in/{ciudad}?format=%C+%t" async with httpx.AsyncClient() as client: response = await client.get(url) if response.status_code == 200: clima = response.text.strip() return [TextContent(type="text", text=C%F3mo%20crear%20tu%20primer%20Plugin%20MCP%20en%20Python%20en%2010%20minutos"Clima en {ciudad}: {clima}")] else: return [TextContent(type="text", text=C%F3mo%20crear%20tu%20primer%20Plugin%20MCP%20en%20Python%20en%2010%20minutos"No se pudo obtener el clima para {ciudad}")] raise ValueError(f"Herramienta desconocida: {name}") async def main(): async with stdio_server() as (read_stream, write_stream): await app.run(read_stream, write_stream, app.create_initialization_options()) if __name__ == "__main__": asyncio.run(main()) Ahora tu plugin tiene dos herramientas reales: una que hace cálculos financieros y otra que consulta una API externa. Fíjate en los detalles importantes: cada herramienta tiene un inputSchema que define los parámetros que acepta, y la función call_tool los recibe en un diccionario. Esto permite que el cliente IA entienda qué necesita y cómo pedirlo.

Paso 3: Prueba tu plugin y resuelve errores comunes

Para probar tu plugin, necesitas un cliente MCP. La forma más rápida es usar el depurador oficial de MCP. Instálalo con pip install mcp-cli y luego ejecuta:

Terminalmcp-cli run server.py Esto iniciará el servidor y te permitirá probar las herramientas con comandos como:

Terminal (dentro de mcp-cli)call calcular_iva {"precio_base": 100, "porcentaje_iva": 21} call obtener_clima {"ciudad": "Madrid"} Si todo funciona, verás las respuestas. Si encuentras errores, los más comunes son:

ErrorCausaSolución ModuleNotFoundError: No module named 'mcp'No instalaste la libreríaEjecuta pip install mcp ValueError: Herramienta desconocidaEl nombre de la herramienta no coincideRevisa que el string en call_tool sea exactamente igual al definido en list_tools httpx.ConnectErrorNo hay conexión a internetVerifica tu conexión o usa una API local No aparece la herramienta en el clienteEl cliente no reconoce el servidorAsegúrate de que el servidor se ejecute con stdio y que el cliente esté configurado para usar stdio Una vez que pase las pruebas, ya puedes integrarlo con tu asistente favorito. Por ejemplo, en Claude Desktop, solo necesitas añadir la ruta a tu script en la configuración de MCP.

Tip: Para depurar más rápido, usa el modo verbose de mcp-cli: mcp-cli run server.py -v. Esto te mostrará cada petición y respuesta en tiempo real, ayudándote a identificar problemas de formato o de lógica.

Paso 4: Lleva tu plugin al siguiente nivel

Ya tienes un plugin funcional, pero las posibilidades son enormes. Aquí tienes ideas para expandirlo:

• Integración con bases de datos: Conecta tu plugin a SQLite o PostgreSQL para que la IA pueda consultar y modificar datos.
• Automatización de tareas: Crea herramientas que ejecuten scripts del sistema, envíen correos o generen reportes.
• Recursos y prompts: Además de herramientas, MCP permite exponer recursos (datos estáticos o dinámicos) y prompts (plantillas de mensajes). Explora la documentación oficial para añadirlos.
• Seguridad: Si tu plugin va a ejecutar comandos del sistema o acceder a datos sensibles, implementa validaciones y límites de uso.

Para terminar, aquí tienes un prompt funcional que puedes usar directamente con cualquier cliente MCP para probar tu plugin:

PROMPTActúa como un asistente que utiliza un plugin MCP con herramientas de cálculo y clima. Primero, calcula el precio final de un producto que cuesta 150 euros con un IVA del 10%. Luego, obtén el clima actual de Buenos Aires. Finalmente, dime cuánto costaría el producto con el clima de Buenos Aires (solo por curiosidad, no es una operación real). Con este prompt, verás cómo la IA llama secuencialmente a tus herramientas y combina los resultados. En menos de 10 minutos has creado un plugin MCP que extiende las capacidades de cualquier asistente de IA. Ahora solo te queda explorar, experimentar y construir herramientas que resuelvan tus problemas reales.