Como construir um servidor MCP personalizado para Cursor (Código Aberto)

Imagine dar superpoderes ao seu Cursor IDE - como pesquisar automaticamente na web ou analisar seus documentos sem sair do seu editor. Neste tutorial, iremos explorar a criação de um servidor MCP (Modelo Contexto Protocolo) personalizado que adiciona essas capacidades exatas ao Cursor.

💡

Para simplificar seu processo de integração de API, ferramentas como Apidog podem facilitar o teste e a depuração. Baixe o Apidog gratuitamente hoje para gerenciar seus fluxos de trabalho de API de forma eficiente e garantir uma interação tranquila com a API Gemini 2.5 Pro. Neste guia técnico, iremos mostrar como usar a API Gemini 2.5 Pro, desde a configuração até casos de uso avançados, com exemplos claros e passos acionáveis.

button

Por que construir um servidor MCP personalizado?

Servidores MCP permitem que você estenda a funcionalidade do Cursor além de seus recursos integrados. Com seu próprio servidor MCP, você pode:

Adicionar capacidades de pesquisa na web
Criar ferramentas para analisar seus documentos (RAG)
Conectar-se a APIs especializadas
Construir fluxos de trabalho personalizados de IA

Atualizações recentes tornam o desenvolvimento de servidores MCP mais fácil do que nunca - perfeito para iniciantes!

Passo 1: Configurando seu ambiente de desenvolvimento

Pré-requisitos

Antes de começarmos, certifique-se de que você tem:

Cursor IDE (última versão)
Python 3.8+ instalado
Gerenciador de pacotes UV (vamos instalar isso abaixo)
Familiaridade básica com comandos de terminal

Obtendo o modelo inicial

Usaremos um modelo pronto para começar rapidamente:

Clone o repositório:

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

Abra a pasta no Cursor IDE

Passo 2: Configurando o servidor MCP no Cursor

No Cursor, vá para:

Configurações > Configurações do Cursor > MCP > Adicionar Novo Servidor MCP

Configure seu servidor:

Nome: Dê um nome descritivo (ex.: "twitter-demo")
Comando: Vamos usar o gerenciador de pacotes UV

Se você não tem o UV instalado:

pip install uv

Defina o comando para executar seu servidor:

uv --directory /caminho/para/cursor_linkup_mcp run server.py

(Substitua /caminho/para/ pelo local real onde você clonou o repositório)

Clique em "Adicionar" para salvar sua configuração

Passo 3: Testando suas novas ferramentas

Agora que seu servidor está configurado, vamos testar suas capacidades:

1. Ferramenta de pesquisa na web

Isso permite que o Cursor pesquise na web por respostas às suas perguntas.

Como usar:

Abra um novo chat no modo "Agente"

2. Faça uma pergunta que requer busca na web, como:

>> Quem ganhou o último jogo de críquete entre Índia e Austrália?

3. O Cursor usará seu servidor MCP para encontrar e exibir a resposta

2. Ferramenta de Análise de Documentos (RAG)

Isso permite que o Cursor analise seus documentos pessoais.

Como configurar:

No repositório clonado, encontre a pasta data

2. Adicione quaisquer documentos que você deseja analisar (PDFs, arquivos do Word, etc.)

3. No chat, faça perguntas sobre seus documentos:

>> Resuma os pontos principais do meu arquivo sobre como o DeepSeek R1 é treinado.

Veja os resultados:

Como funciona por dentro

Seu servidor MCP atua como uma ponte entre o Cursor e serviços externos:

Quando você faz uma pergunta, o Cursor a envia para seu servidor MCP
O servidor processa a solicitação (pesquisando na web ou analisando documentos)
Os resultados são enviados de volta ao Cursor para exibição

Compreendendo o código do servidor MCP

Este script Python cria um servidor MCP (Modelo Contexto Protocolo) personalizado que adiciona duas poderosas ferramentas de IA ao Cursor: pesquisa na web e análise de documentos (RAG). Vamos detalhar o que cada parte faz:

1. Importando Dependências

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

asyncio: Habilita operações assíncronas (importante para lidar com múltiplas solicitações de forma eficiente)
dotenv: Carrega variáveis de ambiente (como chaves de API) de um arquivo .env
LinkupClient: Lida com a funcionalidade de pesquisa na web
RAGWorkflow: Gerencia a análise de documentos (Geração Aumentada por Recuperação)
FastMCP: O núcleo da estrutura do servidor MCP

2. Configuração Inicial

load_dotenv()

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

load_dotenv(): Carrega configurações sensíveis (como chaves de API) de um arquivo .env
mcp: Cria a instância principal do servidor MCP chamada "linkup-server"
client: Inicializa a ferramenta de pesquisa na web
rag_workflow: Prepara o sistema de análise de documentos

3. Ferramenta de Pesquisa na Web

@mcp.tool()
def web_search(query: str) -> str:
    """Pesquise na web para a consulta fornecida."""
    search_response = client.search(
        query=query,
        depth="standard",  # "standard" ou "deep"
        output_type="sourcedAnswer",  # Opções: "searchResults", "sourcedAnswer" ou "structured"
        structured_output_schema=None,  # Necessário se output_type="structured"
    )
    return search_response

O que isso faz:

Adiciona uma ferramenta chamada web_search ao seu Cursor IDE
Recebe uma query de pesquisa (como "clima atual em Paris")
Pode realizar diferentes tipos de pesquisas:
standard vs deep (quão detalhada a pesquisa deve ser)
Retorna seja resultados brutos (searchResults) ou respostas processadas (sourcedAnswer)
Retorna os resultados da pesquisa ao Cursor

Exemplo de uso no Cursor:

/web_search query="Quem ganhou a Copa do Mundo de Críquete de 2023?"

4. Ferramenta de Análise de Documentos (RAG)

@mcp.tool()
async def rag(query: str) -> str:
    """Use RAG para responder consultas usando documentos do diretório de dados"""
    response = await rag_workflow.query(query)
    return str(response)

O que isso faz:

Cria uma ferramenta chamada rag (Geração Aumentada por Recuperação)
Analisa documentos que você colocou na pasta /data
Responde perguntas com base nesses documentos
Funciona de forma assíncrona para melhor desempenho com arquivos grandes

Exemplo de uso no Cursor:

/rag query="Quais são as principais recomendações de segurança neste artigo de IA?"

5. Inicialização do Servidor

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

O que acontece quando você executa isso:

Primeiro, carrega todos os documentos da pasta data na memória
Inicia o servidor MCP usando comunicação stdio (entrada/saída padrão)
Disponibiliza ambas as ferramentas para o Cursor

💡

Gostaria de adicionar mais Servidores MCP ao seu Claude, Cursor ou Windsurf, certifique-se de conferir HiMCP e descobrir 1682+ Servidores e Clientes MCP incríveis para acelerar seu fluxo de trabalho de programação em IA com facilidade!

HiMCP.ai - Descubra 1682+ Servidores MCP

Principais recursos da implementação do servidor MCP

Segurança: Usa .env para dados sensíveis
Flexibilidade: Oferece diferentes modos de busca (padrão/profundo)
Processamento Local: Analisa seus documentos privados sem enviá-los para a nuvem
Desempenho: Usa operações assíncronas para uma experiência tranquila

Como o Cursor usa este servidor

Você digita um comando no Cursor (como /web_search)
O Cursor envia sua consulta para este servidor em execução
O servidor processa (pesquisando na web ou analisando documentos)
Os resultados são retornados ao Cursor e exibidos para você

Isso transforma seu Cursor IDE em um poderoso assistente de pesquisa que pode tanto pesquisar na web quanto analisar seus documentos pessoais - tudo por meio de simples comandos de chat!

Dicas de Solução de Problemas

Se algo não estiver funcionando:

Verifique se o comando UV aponta para o local correto
Certifique-se de que todas as dependências estão instaladas (execute pip install -r requirements.txt)
Verifique se sua versão do Python é 3.8 ou superior
Verifique os logs de erro do Cursor se o servidor falhar ao iniciar

Próximos Passos:

Agora que você tem um servidor MCP básico em funcionamento, você pode:

Adicionar mais ferramentas (como integração com a API do Twitter)
Personalizar os parâmetros de pesquisa na web
Melhorar a análise de documentos com melhores comandos
Compartilhar seu servidor com colegas de equipe

Considerações Finais

Construir seu primeiro servidor MCP pode parecer assustador, mas como você viu, o modelo torna tudo simples. Em menos de 30 minutos, você adicionou novas e poderosas capacidades ao Cursor que economizarão horas de trabalho manual.

O que você irá construir a seguir? Talvez uma ferramenta para:

Verificar preços de ações
Pesquisar através do seu código
Gerar postagens em redes sociais

As possibilidades são infinitas! Lembre-se, todo especialista já foi um iniciante - você acaba de dar seu primeiro passo no mundo do desenvolvimento de servidores MCP.

E enquanto você está nisso, não se esqueça de conferir Apidog para potencializar seu fluxo de trabalho de desenvolvimento de MCP e API! 🚀

button