Desearch

Busca com IA, busca no X e busca na web para agentes de IA.

Servidor MCP hospedado

npx add-mcp 'https://mcp.desearch.ai/mcp'

Instala no Claude Code, Codex, Cursor e outros

Documentação

Servidor MCP Desearch

Se o Desearch for útil, uma estrela ajuda outras pessoas a encontrá-lo.

Remoto: https://mcp.desearch.ai/mcp com cabeçalho Authorization: Bearer <DESEARCH_API_KEY>.

Local: npx -y desearch-mcp-server com env DESEARCH_API_KEY.

Obtenha uma chave.

Encontre o Desearch em

Demonstração

Prompt: Pesquise na web as últimas notícias sobre IA.

web-search recebe query (obrigatório) e start (deslocamento de paginação opcional: 0, 10, 20, ...).

{
    "name": "web-search",
    "arguments": {
        "query": "latest news on AI"
    }
}

Exemplo de saída:

{
    "data": [
        {
            "title": "Example result",
            "link": "https://example.com/page",
            "snippet": "Short preview text."
        }
    ]
}

A ferramenta retorna esse JSON como texto formatado: { "content": [{ "type": "text", "text": "<json above>" }] }.

Pesquisa de IA, pesquisa no X e pesquisa na web para agentes de IA, além de extração de páginas e ferramentas de dados do X. Traga sua própria chave de API do Desearch.

Ferramentas

O servidor MCP Desearch inclui as seguintes ferramentas:

Pesquisa de IA (ai-search): Realiza pesquisas de IA no Twitter e na web com links relevantes e resumo. tools usa IDs de fonte curtos (web, twitter, arxiv, wikipedia, hackernews, reddit). Rótulos mais antigos, como Web Search, ArXiv Search, Wikipedia Search, Hacker News Search e Reddit Search, ainda são aceitos e enviados como o ID curto. youtube não é aceito. O padrão é ["web", "twitter"].
Pesquisa no X (x-search): Pesquisa de tweets no X. Argumentos: query (obrigatório), count (opcional, padrão 20). A ordenação permanece como Top. Filtros opcionais: user, start_date, end_date (AAAA-MM-DD), lang, verified, blue_verified, is_quote, is_video, is_image, min_retweets, min_replies, min_likes.
Pesquisa na Web (web-search): Pesquisa na web no estilo SERP. Argumentos: query (obrigatório), start (deslocamento de paginação opcional).
Pesquisa de Links na Web (web-links-search): Pesquisa de links na web. Argumentos: prompt (obrigatório), tools (opcional, apenas web, padrão ["web"]; Web Search é aceito e reescrito para web), count (opcional, 10–200). A API de links/web rejeita outras fontes, portanto elas não estão no enum.
Extrair (extract): Lê uma URL pública como texto ou HTML. Preferível ao crawl. Argumentos: url (obrigatório), format (opcional, html ou text), js (opcional), wait (milissegundos opcionais).
Crawl na Web (web-crawl): Mesmos argumentos de extract, na rota legada /web/crawl. O SDK marca webCrawl como obsoleto em favor de extract; esta ferramenta permanece para que essa rota continue acessível. Prefira extract para novas integrações.
Pesquisa de Links no X (x-links-search): Pesquisa de IA para links de posts no X. Argumentos: prompt (obrigatório), count (opcional, 10–200).
Posts do X por URLs (x-posts-by-urls): Posts completos para uma lista de URLs. Argumento: urls (obrigatório).
Post do X por ID (x-post-by-id): Um post por ID. Argumento: id (obrigatório).
Posts do X por Usuário (x-posts-by-user): Posts de um usuário. Argumentos: user (obrigatório), query (opcional), count (opcional, 1–100).
Retweets de Post do X (x-post-retweeters): Usuários que retweetaram um post. Argumentos: id (obrigatório), cursor (opcional).
Posts de Usuário no X (x-user-posts): Linha do tempo de um usuário. Argumentos: username (obrigatório), cursor (opcional).
Respostas de Usuário no X (x-user-replies): Posts e respostas de um usuário. Argumentos: user (obrigatório), count (opcional, 1–100), query (opcional).
Respostas a Post no X (x-post-replies): Respostas a um post. Argumentos: post_id (obrigatório), count (opcional, 1–100), query (opcional).
Tendências do X (x-trends): Tópicos em alta para um local. Argumentos: woeid (obrigatório), count (opcional, 30–100).

O mapa completo de método do SDK → endpoint → ferramenta MCP está em docs/API_MCP_PARITY.md. Todo método público do desearch-js 1.5 é uma ferramenta. latestTweets foi removido do SDK (GET /twitter/latest em 1.0.1) e não é exposto.

Pré-requisitos 📋

Uma Chave de API do Desearch
Node.js (v20.18.1 ou superior; Node 22 é suportado. Node 18 não é.)
Claude Desktop instalado
Cursor IDE

Instalação 🛠️

Instalação via NPM

O nome do pacote é desearch-mcp-server. A versão atual está no npm. Consulte CHANGELOG.md para notas de versão. A entrada stdio é o bin desearch-mcp-server (build/index.js), que requer DESEARCH_API_KEY.

npm install -g desearch-mcp-server

Ou execute sem instalação global:

npx -y desearch-mcp-server

Cursor ou Claude podem iniciar esse bin diretamente:

{
    "mcpServers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

command: "desearch-mcp-server" (sem args) é a mesma entrada após a instalação global acima.

Gemini CLI

Instale a extensão deste repositório. O Gemini CLI solicita sua chave de API do Desearch (armazenada como uma configuração sensível) e se conecta ao servidor hospedado https://mcp.desearch.ai/mcp:

gemini extensions install https://github.com/Desearch-ai/mcp-desearch

Para alterar a chave depois, execute gemini extensions config desearch. Agentes de IA como o Cline podem seguir llms-install.md para configurar o servidor.

Usando Smithery

Para instalar o servidor MCP Desearch para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install desearch/desearch --client claude

Ou para Cursor IDE:

npx -y @smithery/cli install desearch/desearch --client cursor

Windsurf

O agente Cascade do Windsurf lê servidores MCP de mcp_config.json sob a chave mcpServers. Abra-o pelo painel Cascade: clique no menu ... (Ações) e depois em Open MCP config file. Builds do Windsurf usam ~/.codeium/windsurf/mcp_config.json (no Windows, %USERPROFILE%\.codeium\windsurf\mcp_config.json). Builds mais novos podem abrir ~/.config/devin/mcp_config.json (Windows: %APPDATA%\devin\mcp_config.json); edite o arquivo que essa ação abrir.

Servidor hospedado (sem instalação local). Servidores remotos usam serverUrl com headers:

{
    "mcpServers": {
        "desearch": {
            "serverUrl": "https://mcp.desearch.ai/mcp",
            "headers": {
                "x-api-key": "your-api-key"
            }
        }
    }
}

Para manter a chave fora do arquivo, o Windsurf pode interpolar uma variável de ambiente: "x-api-key": "${env:DESEARCH_API_KEY}".

Alternativa local via stdio:

{
    "mcpServers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

Salve o arquivo e atualize a lista de servidores MCP no Cascade.

Zed

O Zed chama servidores MCP de servidores de contexto. Abra seu arquivo de configurações com a ação zed: open settings file (ou use Configurações → IA → Servidores MCP → Add Server) e adicione uma entrada context_servers.

Servidor hospedado:

{
    "context_servers": {
        "desearch": {
            "url": "https://mcp.desearch.ai/mcp",
            "headers": {
                "x-api-key": "your-api-key"
            }
        }
    }
}

Alternativa local via stdio:

{
    "context_servers": {
        "desearch": {
            "command": "npx",
            "args": ["-y", "desearch-mcp-server"],
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

O servidor está pronto quando o ponto ao lado de desearch em Configurações → IA → Servidores MCP ficar verde ("Servidor ativo").

Configuração ⚙️

1. Configurar o Cursor IDE para executar o servidor MCP Desearch

Abra o Cursor IDE, acesse a paleta de comandos Cmd+Shift+P ou Ctrl+Shift+P e pesquise por Open MCP Settings. Clique em Add new global MCP server para abrir o arquivo mcp.json.

2. Adicione a configuração do servidor Desearch:

{
    "mcpServers": {
        "desearch": {
            "command": "desearch-mcp-server",
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

Substitua your-api-key pela sua chave real de API do Desearch de console.desearch.ai/api-keys.

3. Reinicie o Cursor IDE

Para que as alterações tenham efeito:

Saia completamente do Cursor IDE
Inicie o Cursor IDE novamente

1. Configurar o Claude Desktop para executar o servidor MCP Desearch

Abra o aplicativo Claude Desktop e ative o Modo Desenvolvedor no menu superior esquerdo.

Depois de ativado, abra Configurações (também no menu superior esquerdo) e navegue até a Opção de Desenvolvedor, onde você encontrará o botão Editar Config. Clicar nele abrirá o arquivo claude_desktop_config.json, permitindo que você faça as edições necessárias.

OU (se quiser abrir claude_desktop_config.json pelo terminal)

Para macOS:

Abra sua configuração do Claude Desktop:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Para Windows:

Abra sua configuração do Claude Desktop:

code %APPDATA%\Claude\claude_desktop_config.json

2. Adicione a configuração do servidor Desearch:

{
    "mcpServers": {
        "desearch": {
            "command": "desearch-mcp-server",
            "env": {
                "DESEARCH_API_KEY": "your-api-key"
            }
        }
    }
}

Substitua your-api-key pela sua chave real de API do Desearch de console.desearch.ai/api-keys.

3. Reinicie o Claude Desktop

Para que as alterações tenham efeito:

Saia completamente do Claude Desktop
Inicie o Claude Desktop novamente
Você pode verificar o servidor verificando o status em Configurações > Desenvolvedor > desearch

HTTP Streamable Remoto

O mesmo servidor pode ser executado via MCP Streamable HTTP para um cliente remoto. O stdio local (desearch-mcp-server, Smithery) permanece inalterado e ainda lê DESEARCH_API_KEY do ambiente.

Requisições remotas não usam essa variável de ambiente. A descoberta não precisa de chave: initialize, notifications/initialized, ping, tools/list, prompts/list, resources/list e resources/templates/list retornam 200 para que um scanner de marketplace possa ler a lista de ferramentas. tools/call e todos os outros métodos ainda exigem a chave de API do Desearch do chamador, a mesma chave de console.desearch.ai/api-keys:

Authorization: Bearer <DESEARCH_API_KEY> (preferido)
x-api-key: <DESEARCH_API_KEY>

Um valor Authorization: <DESEARCH_API_KEY> simples também é aceito. A chave não é lida da string de consulta. Não há segredo de servidor compartilhado e nenhum desafio WWW-Authenticate: o processo hospedado encaminha a chave por requisição para a API Desearch apenas quando uma chamada precisa dela.

O endpoint MCP é POST /mcp. As respostas são JSON (Streamable HTTP sem estado). GET e DELETE em /mcp retornam 405 porque o servidor não mantém uma sessão nem envia mensagens servidor-para-cliente. GET /, GET /health e GET /api/health são verificações de saúde não autenticadas.

Endpoint hospedado

O endpoint público Streamable HTTP é https://mcp.desearch.ai/mcp. Listar as ferramentas não precisa de chave. Envie sua chave de API do Desearch em cada tools/call no cabeçalho x-api-key. Authorization: Bearer <key> também é aceito. Use a chave de console.desearch.ai/api-keys. O servidor não lê uma chave da string de consulta. Requisições remotas não usam um DESEARCH_API_KEY em nível de processo.

Cursor, ou qualquer cliente MCP remoto:

{
    "mcpServers": {
        "desearch": {
            "url": "https://mcp.desearch.ai/mcp",
            "headers": {
                "x-api-key": "your-api-key"
            }
        }
    }
}

Uso com Claude (conector personalizado)

O Desearch ainda não está no Diretório de Conectores do Claude. Você pode adicionar o servidor hospedado como um conector personalizado com sua chave de API do Desearch.

Fontes: Conectores MCP remotos personalizados e autenticação de conectores. Autenticação por cabeçalho de requisição é um recurso beta no Claude.

Claude.ai / Claude Desktop (administrador da organização)

Abra Configurações da organização > Conectores.
Selecione Adicionar e depois Personalizado. Se solicitado o tipo de conector, escolha Web.
URL do servidor: https://mcp.desearch.ai/mcp
Opção de login: Sem login.
Em Cabeçalhos de requisição, adicione x-api-key com sua chave de API do Desearch como valor.
Selecione Adicionar.

O valor do cabeçalho é armazenado uma vez e compartilhado por todos na organização que usam o conector.

Claude Code

claude mcp add --transport http desearch https://mcp.desearch.ai/mcp \
  --header "x-api-key: YOUR_DESEARCH_API_KEY"

Executar localmente

npm install
npm run build
npm run start:http

Isso escuta em 0.0.0.0:3000 (PORT e HOST substituem isso). MCP_TRANSPORT=http é o mesmo que --http.

curl -sS http://127.0.0.1:3000/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Authorization: Bearer your-api-key' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"smoke","version":"0.0.1"}}}'

Cursor (ou qualquer cliente MCP remoto):

{
    "mcpServers": {
        "desearch": {
            "url": "http://127.0.0.1:3000/mcp",
            "headers": {
                "Authorization": "Bearer your-api-key"
            }
        }
    }
}

O padrão da imagem é stdio MCP (node build/index.js). Registros como Glama iniciam o contêiner e falam MCP em stdin/stdout, então a imagem não passa --http a menos que você substitua. Stdio requer DESEARCH_API_KEY. Smithery não usa este comando de imagem; smithery.yaml inicia node build/index.js e injeta DESEARCH_API_KEY ele mesmo.

Streamable HTTP é uma substituição. Substitua o comando por --http, ou defina MCP_TRANSPORT=http e mantenha o comando padrão. A imagem ainda expõe a porta 3000 para esse modo.

docker build -t desearch-mcp .
# stdio (image default)
docker run --rm -e DESEARCH_API_KEY=your-api-key -i desearch-mcp
# Streamable HTTP
docker run --rm -p 3000:3000 desearch-mcp node build/index.js --http
# same HTTP mode via env, without replacing the command
docker run --rm -e MCP_TRANSPORT=http -p 3000:3000 desearch-mcp

Implantar no Vercel

Vercel se encaixa neste servidor porque o handler não tem estado e responde a cada chamada JSON-RPC em uma única resposta. vercel.json compila o projeto, serve POST /mcp e define a duração da função para 60 segundos. Os planos Hobby limitam a duração da função a um valor menor que esse, então chamadas de ferramenta do AI Search precisam de um plano que permita pelo menos 60 segundos. initialize e tools/list são curtos de qualquer forma.

Nenhuma chave de API Desearch no lado do servidor é necessária no projeto Vercel. Após o deploy, o endpoint é:

https://<project>.vercel.app/mcp

https://mcp.desearch.ai/mcp é o hostname público. Este repositório não cria registros DNS. Os clientes enviam x-api-key, ou Authorization: Bearer <key>.

O mesmo processo node build/index.js --http é o fallback se você preferir executar um host Node de longa duração em vez do Vercel. A imagem Docker usa stdio por padrão; passe --http ou defina MCP_TRANSPORT=http para servir Streamable HTTP a partir dela.

Solução de Problemas 🔧

Problemas Comuns

Servidor Não Encontrado
- Verifique a sintaxe de configuração do Claude ou Cursor Desktop
- Garanta que o Node.js esteja instalado
Problemas com Chave de API
- Confirme que sua DESEARCH_API_KEY é válida
- Verifique se a DESEARCH_API_KEY está configurada corretamente no config do Cursor ou Claude Desktop
- Confirme que não há espaços ao redor da chave de API
- Para o servidor HTTP remoto, envie Authorization: Bearer <key> ou x-api-key. Uma variável de ambiente DESEARCH_API_KEY hospedada não é usada para essas solicitações.
Problemas de Conexão
- Reinicie o Claude Desktop ou o IDE Cursor completamente
- Verifique os logs do Claude Desktop:
```
# macOS
tail -n 50 -f ~/Library/Logs/Claude/mcp*.log

# Windows
type "%APPDATA%\Claude\logs\mcp*.log"
```