Cómo construir un servidor MCP personalizado para Cursor (Código Abierto)

Imagina darle superpoderes a tu Cursor IDE, como buscar automáticamente en la web o analizar tus documentos sin salir de tu editor. En este tutorial, te guiaremos a través de la creación de un servidor MCP (Model Context Protocol) personalizado que agrega estas capacidades exactas a Cursor.

¿Por qué construir un servidor MCP personalizado?

Los servidores MCP te permiten extender la funcionalidad de Cursor más allá de sus características integradas. Con tu propio servidor MCP, puedes:

• Añadir capacidades de búsqueda web
• Crear herramientas para analizar tus documentos (RAG)
• Conectar a APIs especializadas
• Construir flujos de trabajo de IA personalizados

Las actualizaciones recientes hacen que el desarrollo del servidor MCP sea más fácil que nunca, ¡perfecto para principiantes!

Paso 1: Configurando tu entorno de desarrollo

Prerrequisitos

Antes de comenzar, asegúrate de tener:

1. Cursor IDE (última versión)
2. Python 3.8+ instalado
3. Administrador de paquetes UV (lo instalaremos a continuación)
4. Familiaridad básica con los comandos de la terminal

Obteniendo la plantilla de inicio

Usaremos una plantilla ya preparada para comenzar rápidamente:

1. Clona el repositorio:

git clone https://github.com/patchy631/ai-engineering-hub/tree/main/cursor_linkup_mcp

1. Abre la carpeta en Cursor IDE

Paso 2: Configurando el servidor MCP en Cursor

En Cursor, ve a:

Settings > Cursor Settings > MCP > Add New MCP Server

Configura tu servidor:

• Name: Dale un nombre descriptivo (p. ej., "twitter-demo")
• Command: Usaremos el administrador de paquetes UV

Si no tienes UV instalado:

pip install uv

Establece el comando para ejecutar tu servidor:

uv --directory /path/to/cursor_linkup_mcp run server.py

(Reemplaza /path/to/ con la ubicación real donde clonaste el repositorio)

Haz clic en "Add" para guardar tu configuración

Paso 3: Probando tus nuevas herramientas

Ahora que tu servidor está configurado, probemos sus capacidades:

1. Herramienta de búsqueda web

Esto permite a Cursor buscar en la web respuestas a tus preguntas.

Cómo usar:

1. Abre un nuevo chat en modo "Agent"

2. Haz una pregunta que requiera una búsqueda web, como:

>> Who won the latest cricket match between India and Australia?

3. Cursor usará tu servidor MCP para encontrar y mostrar la respuesta

2. Herramienta RAG (Análisis de documentos)

Esto permite a Cursor analizar tus documentos personales.

Cómo configurar:

1. En el repositorio clonado, encuentra la carpeta data

2. Agrega cualquier documento que quieras analizar (PDFs, archivos de Word, etc.)

3. En el chat, haz preguntas sobre tus documentos:

>> Summarize the key points from my file about how DeepSeek R1 is trained.

Ver los resultados:

Cómo funciona internamente

Tu servidor MCP actúa como un puente entre Cursor y los servicios externos:

1. Cuando haces una pregunta, Cursor la envía a tu servidor MCP
2. El servidor procesa la solicitud (buscando en la web o analizando documentos)
3. Los resultados se envían de vuelta a Cursor para su visualización

Entendiendo el código del servidor MCP

Este script de Python crea un servidor MCP (Model Context Protocol) personalizado que agrega dos potentes herramientas de IA a Cursor: búsqueda web y análisis de documentos (RAG). Desglosemos lo que hace cada parte:

1. Importando dependencias

import asyncio
from dotenv import load_dotenv
from linkup import LinkupClient
from rag import RAGWorkflow
from mcp.server.fastmcp import FastMCP

• asyncio: Permite operaciones asíncronas (importante para manejar múltiples solicitudes de manera eficiente)
• dotenv: Carga variables de entorno (como claves de API) desde un archivo .env
• LinkupClient: Maneja la funcionalidad de búsqueda web
• RAGWorkflow: Gestiona el análisis de documentos (Generación Aumentada por Recuperación)
• FastMCP: El marco central del servidor MCP

2. Configuración inicial

load_dotenv()

mcp = FastMCP('linkup-server')
client = LinkupClient()
rag_workflow = RAGWorkflow()

• load_dotenv(): Carga la configuración sensible (como las claves de API) desde un archivo .env
• mcp: Crea la instancia principal del servidor MCP llamada "linkup-server"
• client: Inicializa la herramienta de búsqueda web
• rag_workflow: Prepara el sistema de análisis de documentos

3. Herramienta de búsqueda web

@mcp.tool()
def web_search(query: str) -> str:
    """Search the web for the given query."""
    search_response = client.search(
        query=query,
        depth="standard",  # "standard" or "deep"
        output_type="sourcedAnswer",  # Options: "searchResults", "sourcedAnswer", or "structured"
        structured_output_schema=None,  # Required if output_type="structured"
    )
    return search_response

Qué hace:

• Añade una herramienta llamada web_search a tu Cursor IDE
• Toma una query de búsqueda (como "clima actual en París")
• Puede realizar diferentes tipos de búsquedas:
• standard vs deep (cuán exhaustiva debe ser la búsqueda)
• Devuelve resultados sin procesar (searchResults) o respuestas procesadas (sourcedAnswer)
• Devuelve los resultados de la búsqueda a Cursor

Ejemplo de uso en Cursor:

/web_search query="Who won the 2023 Cricket World Cup?"

4. Herramienta de análisis de documentos (RAG)

@mcp.tool()
async def rag(query: str) -> str:
    """Use RAG to answer queries using documents from the data directory"""
    response = await rag_workflow.query(query)
    return str(response)

Qué hace:

• Crea una herramienta llamada rag (Generación Aumentada por Recuperación)
• Analiza los documentos que has colocado en la carpeta /data
• Responde preguntas basadas en esos documentos
• Funciona de forma asíncrona para un mejor rendimiento con archivos grandes

Ejemplo de uso en Cursor:

/rag query="What are the key safety recommendations in this AI paper?"

5. Inicio del servidor

if __name__ == "__main__":
    asyncio.run(rag_workflow.ingest_documents("data"))
    mcp.run(transport="stdio")

Qué sucede cuando ejecutas esto:

1. Primero carga todos los documentos de la carpeta data en la memoria
2. Inicia el servidor MCP usando la comunicación stdio (entrada/salida estándar)
3. Hace que ambas herramientas estén disponibles para Cursor

Características clave de la implementación del servidor MCP

1. Seguridad: Utiliza .env para datos sensibles
2. Flexibilidad: Ofrece diferentes modos de búsqueda (estándar/profundo)
3. Procesamiento local: Analiza tus documentos privados sin enviarlos a la nube
4. Rendimiento: Utiliza operaciones asíncronas para una experiencia fluida

Cómo usa Cursor este servidor

1. Escribes un comando en Cursor (como /web_search)
2. Cursor envía tu consulta a este servidor en ejecución
3. El servidor lo procesa (buscando en la web o analizando documentos)
4. Los resultados se devuelven a Cursor y se te muestran

Esto convierte tu Cursor IDE en un potente asistente de investigación que puede tanto buscar en la web como analizar tus documentos personales, ¡todo a través de simples comandos de chat!

Consejos para la resolución de problemas

Si algo no funciona:

1. Verifica que el comando UV apunte a la ubicación correcta
2. Asegúrate de que todas las dependencias estén instaladas (ejecuta pip install -r requirements.txt)
3. Verifica que tu versión de Python sea 3.8 o superior
4. Consulta los registros de errores de Cursor si el servidor no se inicia

Próximos pasos:

Ahora que tienes un servidor MCP básico en funcionamiento, puedes:

• Añadir más herramientas (como la integración de la API de Twitter)
• Personalizar los parámetros de búsqueda web
• Mejorar el análisis de documentos con mejores indicaciones
• Compartir tu servidor con compañeros de equipo

Reflexiones finales

Construir tu primer servidor MCP puede parecer desalentador, pero como has visto, la plantilla lo hace sencillo. En menos de 30 minutos, has añadido nuevas y potentes capacidades a Cursor que te ahorrarán horas de trabajo manual.

¿Qué construirás a continuación? Tal vez una herramienta para:

• Consultar los precios de las acciones
• Buscar en tu base de código
• Generar publicaciones en redes sociales

¡Las posibilidades son infinitas! Recuerda, todo experto fue una vez un principiante: acabas de dar tu primer paso en el mundo del desarrollo de servidores MCP.

Y mientras lo haces, no olvides consultar Apidog para potenciar tu flujo de trabajo de desarrollo de MCP y API. 🚀