Perplexity Ask MCP Server

oficial

Um conector para a API Perplexity que permite pesquisa na web dentro do ecossistema MCP.

O que você pode fazer com Perplexity Ask MCP?

  • Pesquisa web em tempo real — Solicite resultados de busca atuais e ranqueados com filtros de recência, restrições de domínio ou modo rápido via perplexity_search.
  • Perguntas e respostas conversacionais — Obtenha respostas rápidas e baseadas na web para perguntas do dia a dia usando a ferramenta perplexity_ask.
  • Relatórios de pesquisa aprofundada — Solicite análises abrangentes e de múltiplas etapas para investigações minuciosas via perplexity_research.
  • Raciocínio avançado — Enfrente problemas analíticos complexos com solução passo a passo por meio do perplexity_reason.
  • Profundidade de busca personalizável — Controle o contexto de busca recuperado definindo orçamentos de max_tokens e max_tokens_per_page para as ferramentas de perguntas e raciocínio.

Documentação

Servidor MCP da Plataforma de API Perplexity

Install in Cursor   Install in VS Code   Add to Kiro   npm version

A implementação oficial do servidor MCP para a Plataforma de API Perplexity, fornecendo aos assistentes de IA pesquisa na web em tempo real, raciocínio e capacidades de pesquisa por meio da Agent API e da Search API.

Servidor MCP Remoto

O servidor MCP remoto é hospedado pela Perplexity e é a maneira mais fácil de começar: mesmas ferramentas, nada para instalar ou atualizar. Os botões Cursor e VS Code no topo desta página conectam-se a ele com um clique. Se o seu cliente MCP ainda não suporta servidores remotos, vá para a configuração do servidor local abaixo. Conecte via Streamable HTTP com sua chave de API Perplexity:

https://api.perplexity.ai/mcp

Para Claude Code:

claude mcp add --transport http perplexity https://api.perplexity.ai/mcp --header "Authorization: Bearer YOUR_API_KEY"

Consulte a documentação de integração MCP para configuração manual do Cursor/VS Code, uso a partir da API Anthropic e configuração para outros clientes.

Servidor MCP Local

Obtenha Sua Chave de API

  1. Obtenha sua chave de API Perplexity no Portal de API
  2. Substitua your_key_here nas configurações abaixo pela sua chave de API
  3. (Opcional) Defina o tempo limite: PERPLEXITY_TIMEOUT_MS=600000 (padrão: 5 minutos)
  4. (Opcional) Defina URL base personalizada: PERPLEXITY_BASE_URL=https://your-custom-url.com (padrão: https://api.perplexity.ai)
  5. (Opcional) Defina o nível de log: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (padrão: ERROR)

Claude Code

claude mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Ou instale via plugin:

export PERPLEXITY_API_KEY="your_key_here"
claude
# Then run: /plugin marketplace add perplexityai/modelcontextprotocol
# Then run: /plugin install perplexity

Codex

codex mcp add perplexity --env PERPLEXITY_API_KEY="your_key_here" -- npx -y @perplexity-ai/mcp-server

Plugins de Agente

Este repositório é empacotado como um Agent Plugin, então clientes que suportam o padrão podem instalá-lo diretamente deste repositório. O formato Agent Plugins não carrega segredos, então defina a variável de ambiente PERPLEXITY_API_KEY por meio das configurações de plugin ou MCP do seu cliente.

Outros Clientes MCP

A maioria dos clientes pode ser configurada manualmente usando o mesmo wrapper mcpServers na configuração do cliente (como mostrado para Cursor). Se um cliente tiver um esquema diferente, verifique sua documentação para o formato exato do wrapper.

Para configuração manual, esses clientes usam todos a mesma estrutura mcpServers:

ClienteArquivo de Configuração
Cursor~/.cursor/mcp.json
Claude Desktopclaude_desktop_config.json
Kiro.kiro/settings/mcp.json
Windsurf~/.codeium/windsurf/mcp_config.json
VS Code.vscode/mcp.json
{
  "mcpServers": {
    "perplexity": {
      "command": "npx",
      "args": ["-y", "@perplexity-ai/mcp-server"],
      "env": {
        "PERPLEXITY_API_KEY": "your_key_here"
      }
    }
  }
}

Configuração de Proxy (Para Redes Corporativas)

Se você estiver executando este servidor no trabalho—especialmente atrás de um firewall ou proxy corporativo—pode ser necessário informar ao programa como enviar seu tráfego de internet através do proxy da sua rede. Siga estes passos:

1. Obtenha os detalhes do seu proxy

  • Pergunte ao seu departamento de TI pelo endereço e porta do seu proxy HTTPS.
  • Você também pode precisar de um nome de usuário e senha.

2. Defina a variável de ambiente do proxy

A maneira mais fácil e confiável para o Perplexity MCP é usar PERPLEXITY_PROXY. Por exemplo:

export PERPLEXITY_PROXY=https://your-proxy-host:8080

Se o seu proxy precisar de nome de usuário e senha, use:

export PERPLEXITY_PROXY=https://username:password@your-proxy-host:8080

3. Alternativa: Variáveis de ambiente padrão

Se preferir usar as variáveis padrão, suportamos HTTPS_PROXY e HTTP_PROXY.

[!NOTE] O servidor verifica as configurações de proxy nesta ordem: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. Se nenhuma estiver definida, ele se conecta diretamente à internet. As URLs devem incluir https://. As portas típicas são 8080, 3128 e 80.

Modo HTTP Auto-hospedado

Para implantações em nuvem ou compartilhadas, execute o servidor em modo HTTP.

Variáveis de Ambiente

VariávelDescriçãoPadrão
PERPLEXITY_API_KEYSua chave de API PerplexityObrigatória
PERPLEXITY_BASE_URLURL base personalizada para solicitações de APIhttps://api.perplexity.ai
PORTPorta do servidor HTTP8080
BIND_ADDRESSInterface de rede para vincular. O padrão é loopback. Defina como 0.0.0.0 para expor em todas as interfaces.127.0.0.1
ALLOWED_ORIGINSOrigens CORS (separadas por vírgula). O padrão é vazio (sem solicitações de navegador entre origens). Defina uma lista de permissões explícita (por exemplo, https://app.example.com) ou * para permitir qualquer origem.(vazio)
ALLOWED_HOSTSValores adicionais de cabeçalho Host para aceitar (separados por vírgula). Hosts de loopback em PORT são sempre permitidos. Adicione o nome de host público ao vincular a 0.0.0.0.(somente loopback)

Docker

docker build -t perplexity-mcp-server .
docker run -p 8080:8080 -e PERPLEXITY_API_KEY=your_key_here perplexity-mcp-server

Node.js

export PERPLEXITY_API_KEY=your_key_here
npm install && npm run build && npm run start:http

O servidor estará acessível em http://localhost:8080/mcp

Ferramentas Disponíveis

perplexity_search

Os resultados da pesquisa incluem datas de publicação e última atualização quando disponíveis. Datas ausentes ou nulas são omitidas da saída formatada.

Pesquisa web direta usando a Perplexity Search API. Retorna resultados de pesquisa classificados com metadados, perfeito para encontrar informações atuais. Suporta filtros de recência (search_recency_filter), restrições de domínio (search_domain_filter) e Fast Search (search_type: "fast") para menor latência e custo.

perplexity_ask

IA conversacional de propósito geral com pesquisa web em tempo real, apoiada pelo preset fast da Agent API. Ótimo para perguntas rápidas e pesquisas do dia a dia.

perplexity_research

Pesquisa profunda e abrangente apoiada pelo preset high da Agent API. Ideal para análises minuciosas e relatórios detalhados. As execuções podem levar minutos; o servidor transmite a execução e relata o progresso aos clientes que o solicitarem.

perplexity_reason

Raciocínio avançado e resolução de problemas apoiados pelo preset medium da Agent API. Perfeito para tarefas analíticas complexas.

perplexity_ask e perplexity_reason aceitam max_tokens opcional de inteiro positivo (contexto total de pesquisa, até 120.000) e max_tokens_per_page (contexto por página de resultados, até 20.000). Esses orçamentos da Agent API controlam o conteúdo de pesquisa recuperado, não o comprimento da resposta gerada. Quando omitidos, a configuração de pesquisa do preset permanece em vigor.

O argumento legado search_context_size ainda é aceito, mas é traduzido localmente em orçamentos explícitos em vez de ser enviado à Agent API:

Tamanho legadoTotal de tokensTokens por página
low2000512
medium40001024
high80002048

Esta política de compatibilidade não é um equivalente exato dos tamanhos nomeados do Sonar; o guia de migração da Agent API não tem equivalente de tamanho nomeado. Cada orçamento explícito substitui seu padrão legado correspondente.

[!NOTE] Presets são configurações gerenciadas (modelo, configuração de pesquisa, orçamento de etapas) que a Perplexity mantém ajustadas ao longo do tempo; consulte o guia de presets. Versões anteriores deste servidor chamavam os modelos legados sonar-pro, sonar-reasoning-pro e sonar-deep-research e aceitavam os parâmetros strip_thinking / reasoning_effort. Esses parâmetros não fazem mais parte dos esquemas das ferramentas e são ignorados se enviados; a Agent API não produz tags <think>.

Uso como Biblioteca

O pacote também exporta a fábrica do servidor para incorporação em seu próprio processo Node:

import { createPerplexityServer } from "@perplexity-ai/mcp-server";

// Single-tenant: reads PERPLEXITY_API_KEY from the environment.
const server = createPerplexityServer("my-service");

// Multi-tenant hosts resolve the key per call instead. When a provider is
// set, the environment variable is never consulted, and a provider that
// returns no key fails the call rather than falling back.
const tenantServer = createPerplexityServer("my-service", {
  apiKey: () => currentRequestApiKey,
});

Monte o servidor retornado em qualquer transporte MCP (stdio, HTTP streamable, em memória).

Solução de Problemas

  • Problemas com Chave de API: Certifique-se de que PERPLEXITY_API_KEY esteja definida corretamente
  • Erros de Conexão: Verifique sua conexão com a internet e a validade da chave de API
  • Ferramenta Não Encontrada: Certifique-se de que o pacote esteja instalado e o caminho do comando esteja correto
  • Erros de Tempo Limite: Para consultas de pesquisa muito longas, defina PERPLEXITY_TIMEOUT_MS para um valor mais alto
  • Problemas de Proxy: Verifique sua configuração de PERPLEXITY_PROXY ou HTTPS_PROXY e certifique-se de que api.perplexity.ai não esteja bloqueado pelo seu firewall.
  • Erros de EOF / Inicialização: Alguns clientes MCP estritos falham porque npx escreve mensagens de instalação no stdout. Use npx -yq em vez de npx -y para suprimir essa saída.

Para suporte, visite community.perplexity.ai ou abra um problema.