Perplexity Ask MCP Server
oficialUm 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_tokensemax_tokens_per_pagepara as ferramentas de perguntas e raciocínio.
Documentação
Servidor MCP da Plataforma de API Perplexity
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
- Obtenha sua chave de API Perplexity no Portal de API
- Substitua
your_key_herenas configurações abaixo pela sua chave de API - (Opcional) Defina o tempo limite:
PERPLEXITY_TIMEOUT_MS=600000(padrão: 5 minutos) - (Opcional) Defina URL base personalizada:
PERPLEXITY_BASE_URL=https://your-custom-url.com(padrão: https://api.perplexity.ai) - (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:
| Cliente | Arquivo de Configuração |
|---|---|
| Cursor | ~/.cursor/mcp.json |
| Claude Desktop | claude_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 incluirhttps://. As portas típicas são8080,3128e80.
Modo HTTP Auto-hospedado
Para implantações em nuvem ou compartilhadas, execute o servidor em modo HTTP.
Variáveis de Ambiente
| Variável | Descrição | Padrão |
|---|---|---|
PERPLEXITY_API_KEY | Sua chave de API Perplexity | Obrigatória |
PERPLEXITY_BASE_URL | URL base personalizada para solicitações de API | https://api.perplexity.ai |
PORT | Porta do servidor HTTP | 8080 |
BIND_ADDRESS | Interface 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_ORIGINS | Origens 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_HOSTS | Valores 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 legado | Total de tokens | Tokens por página |
|---|---|---|
low | 2000 | 512 |
medium | 4000 | 1024 |
high | 8000 | 2048 |
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-proesonar-deep-researche aceitavam os parâmetrosstrip_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_KEYesteja 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_MSpara um valor mais alto - Problemas de Proxy: Verifique sua configuração de
PERPLEXITY_PROXYouHTTPS_PROXYe certifique-se de queapi.perplexity.ainão esteja bloqueado pelo seu firewall. - Erros de EOF / Inicialização: Alguns clientes MCP estritos falham porque
npxescreve mensagens de instalação no stdout. Usenpx -yqem vez denpx -ypara suprimir essa saída.
Para suporte, visite community.perplexity.ai ou abra um problema.