Perplexity

Servidor MCP Perplexity

Um servidor MCP que fornece recursos de busca na web do Perplexity AI para o Claude, com seleção automática de modelo, filtros com estado e 10 ferramentas criadas para propósitos específicos.

Pré-requisitos

• Node.js v20 ou superior
• Uma chave de API Perplexity — obtenha uma em https://www.perplexity.ai/settings/api
• Claude Desktop (ou qualquer cliente compatível com MCP)

Instalação

1. Clone este repositório:

   git clone https://github.com/RossH121/perplexity-mcp.git
   cd perplexity-mcp
   

2. Instale as dependências:

   npm install
   

3. Compile o servidor:

   npm run build
   

Configuração

Adicione o servidor ao arquivo de configuração do Claude em ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "perplexity-server": {
      "command": "node",
      "args": ["/absolute/path/to/perplexity-mcp/build/index.js"],
      "env": {
        "PERPLEXITY_API_KEY": "your-api-key-here",
        "PERPLEXITY_MODEL": "sonar-pro"
      }
    }
  }
}

Substitua /absolute/path/to pelo caminho real de onde você clonou o repositório.

Modelos Disponíveis

O servidor seleciona automaticamente o melhor modelo com base na sua consulta, mas você também pode definir um padrão via PERPLEXITY_MODEL:

Modelo	Melhor para
sonar-deep-research	Relatórios abrangentes, pesquisa exaustiva com múltiplas fontes
sonar-reasoning-pro	Lógica complexa, matemática, análise de cadeia de raciocínio
sonar-pro	Busca geral, consultas factuais (padrão)
sonar	Consultas rápidas e simples

Para preços e disponibilidade: https://docs.perplexity.ai/guides/pricing

Ferramentas

search — Busca na web com IA

A principal ferramenta de busca. Seleciona automaticamente o modelo certo com base na sua consulta. Retorna uma resposta sintetizada com fontes citadas.

Parâmetro	Opções	Descrição
query	string	Sua consulta de busca
search_context_size	low / medium / high	Quanto contexto da web recuperar. low é o mais rápido/barato (padrão), high é o mais completo
search_type	fast / pro / auto	Nível do mecanismo de busca (aninhado em web_search_options)
reasoning_effort	minimal / low / medium / high	Profundidade do raciocínio para sonar-deep-research
strip_thinking	boolean	Remover blocos <think>...</think> das respostas dos modelos de raciocínio
search_mode	web / academic / sec	academic prioriza artigos revisados por pares; sec busca em documentos da SEC
search_after_date / search_before_date	MM/DD/YYYY	Filtrar fontes por data de publicação
last_updated_after / last_updated_before	MM/DD/YYYY	Filtrar fontes por data da última atualização
search_language_filter	["en","de"]	Restringir fontes a idiomas (ISO 639-1)
language_preference	ISO 639-1	Idioma preferido da resposta
disable_search	boolean	Responder apenas com dados de treinamento (sem busca na web)
enable_search_classifier	boolean	Deixar um classificador decidir se deve buscar
return_images	boolean	Adicionar uma seção de Imagens com URLs dos resultados
image_domain_filter / image_format_filter	string[]	Restringir imagens por domínio ou formato
return_related_questions	boolean	Adicionar sugestões de perguntas de acompanhamento
country / latitude / longitude	—	Localizar resultados via user_location
stream_mode	full / concise	Formato de eventos de streaming para Pro Search
show_cost	boolean	Adicionar rodapé com custo da solicitação quando disponível
stream	boolean	Habilitar respostas em streaming

Exemplos:

• "Quais as novidades sobre energia de fusão?" → seleciona automaticamente sonar-pro
• "Análise de pesquisa aprofundada sobre avanços na edição genética CRISPR" → seleciona automaticamente sonar-deep-research
• "Resolva este quebra-cabeça lógico passo a passo" → seleciona automaticamente sonar-reasoning-pro

raw_search — Resultados classificados brutos (sem LLM)

Retorna resultados da web classificados diretamente, sem síntese de IA. Mais rápido e barato — útil para descoberta de URLs, construção de listas de fontes ou pipelines de verificação de fatos.

Parâmetro	Opções	Descrição
query	string ou string[]	Consulta de busca, ou um array de consultas executadas em uma única solicitação
max_results	1–20	Número de resultados (padrão: 10)
max_tokens / max_tokens_per_page	number	Orçamento de tokens geral / por resultado
search_mode	web / academic / sec	Categoria da fonte
search_type	web / people	people direciona para Pesquisa de Pessoas
recency	hour / day / week / month / year	Filtro de janela de tempo
search_after_date / search_before_date	MM/DD/YYYY	Filtrar por data de publicação
last_updated_after / last_updated_before	MM/DD/YYYY	Filtrar por data da última atualização
search_language_filter	["en","de"]	Restringir a idiomas (ISO 639-1)
country	código ISO 3166	Localizar resultados (ex.: US, GB)

Nota: versões anteriores enviavam esses parâmetros em camelCase, que a API de Busca ignorava silenciosamente — então max_results, recency, search_mode e os filtros de data não tinham efeito. Isso foi corrigido; agora eles têm efeito.

async_research — Pesquisa aprofundada de longa duração

Envie um job sonar-deep-research e faça polling, em vez de bloquear em uma chamada síncrona. Útil quando a pesquisa pode exceder o tempo limite síncrono de 5 minutos. Jobs expiram 7 dias após a criação.

Parâmetro	Opções	Descrição
action	submit / status / list	O que fazer
query	string	Pergunta de pesquisa (obrigatório para submit)
request_id	string	ID do job de um submit anterior (obrigatório para status)
model	modelo Sonar	Modelo do job (padrão: sonar-deep-research)
reasoning_effort	minimal / low / medium / high	Profundidade do raciocínio
search_mode	web / academic / sec	Categoria da fonte
strip_thinking	boolean	Remover blocos <think> do resultado concluído

"Submit async research: comprehensive comparison of solid-state battery startups"
→ returns a request_id
"Check async research status for <request_id>"

agent — Loop agêntico com ferramentas integradas

A API de Agente Perplexity. Executa um agente de múltiplas etapas que pode chamar ferramentas integradas e, opcionalmente, um modelo de terceiros.

Parâmetro	Opções	Descrição
input	string	A tarefa ou pergunta
model	ex.: openai/gpt-4.1	Modelo qualificado por provedor
models	string[]	Cadeia de fallback (tem precedência sobre model)
preset	fast-search / pro-search / deep-research	Predefinição nomeada em vez de um modelo
instructions	string	Prompt do sistema
max_steps	1–10	Máximo de etapas agênticas/ferramentas
max_output_tokens	number	Máximo de tokens de saída
tools	web_search / fetch_url	Ferramentas integradas que o agente pode usar

embeddings — Embeddings de texto

Gera embeddings via API de Embeddings Perplexity. Retorna um resumo compacto (modelo, contagem de vetores, uso de tokens) por padrão.

Parâmetro	Opções	Descrição
input	string ou string[]	Texto(s) para incorporar (máx. 512)
model	pplx-embed-v1-0.6b / pplx-embed-v1-4b	Modelo de embedding (padrão: 0.6b)
dimensions	number	Dimensões de saída (Matryoshka)
full	boolean	Incluir vetores brutos codificados em base64

domain_filter — Domínios de allowlist/blocklist

Restringir ou excluir domínios específicos dos resultados de busca. Os filtros persistem em todas as buscas subsequentes até serem limpos.

• action: "allow" — restringir resultados a este domínio (modo allowlist)
• action: "block" — excluir este domínio dos resultados (modo denylist)
• Máximo de 20 domínios; não é possível misturar allow e block no mesmo conjunto de filtros

"Allow results only from arxiv.org and nature.com"
"Block pinterest.com and reddit.com from search results"

recency_filter — Filtro de janela de tempo

Limitar os resultados de busca a um período específico. Persiste até ser alterado.

Opções: hour, day, week, month, year, none

"Set recency filter to week"
"Remove the recency filter"

clear_filters — Redefinir todos os filtros

Limpa todos os filtros de domínio e recência em uma única chamada.

list_filters — Visualizar filtros ativos

Mostra o allowlist/blocklist de domínios atualmente ativo e a configuração de recência.

model_info — Visualizar ou substituir a seleção de modelo

Visualiza os modelos disponíveis e a seleção atual, ou força manualmente um modelo específico.

"Show model info"
"Set model to sonar-deep-research"

Seleção Inteligente de Modelo

O servidor pontua sua consulta contra listas de palavras-chave para escolher automaticamente o modelo certo:

• Palavras-chave de pesquisa (deep research, comprehensive, in-depth) → sonar-deep-research
• Palavras-chave de raciocínio (solve, logic, mathematical, figure out) → sonar-reasoning-pro
• Palavras-chave simples (quick, brief, basic) → sonar
• Todo o resto → sonar-pro

Cada resposta mostra qual modelo foi usado e por quê. Se uma consulta corresponder fortemente a um modelo (pontuação ≥ 2), ela substituirá um modelo definido manualmente.

Fluxos de Trabalho de Exemplo

Pesquisa sensível ao tempo com filtragem de domínio:

1. recency_filter → week
2. domain_filter → permitir nature.com, permitir arxiv.org
3. search → "Avanços recentes na correção de erros quânticos"

Pesquisa de documentos financeiros:

1. raw_search com search_mode: "sec" → encontrar documentos relevantes
2. search com search_mode: "sec" → análise sintetizada

Revisão de literatura acadêmica:

1. search com search_mode: "academic", search_context_size: "high" → resultados abrangentes de fontes revisadas por pares

Pesquisa aprofundada com controle de raciocínio:

1. search com reasoning_effort: "high", strip_thinking: true → análise completa sem blocos <think> na saída

Desenvolvimento

npm run build   # Compile TypeScript to build/
npm start       # Run the built server

O código-fonte está em src/ — após editar, recompile e reinicie o Claude para carregar as alterações.

Licença

MIT