Perplexity Ask MCP Server

Perplexity API Platform MCP 服务

     

Perplexity API Platform 的官方 MCP 服务实现，通过 Agent API 和 Search API 为 AI 助手提供实时网络搜索、推理和研究能力。

远程 MCP 服务

远程 MCP 服务由 Perplexity 托管，是最快捷的入门方式：工具相同，无需安装或更新。本页顶部的 Cursor 和 VS Code 按钮可一键连接到该服务。如果你的 MCP 客户端尚不支持远程服务，请跳转到下方的本地服务设置。使用你的 Perplexity API 密钥通过 Streamable HTTP 连接：

https://api.perplexity.ai/mcp

对于 Claude Code：

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

请参阅 MCP 集成文档，了解 Cursor/VS Code 手动配置、通过 Anthropic API 使用，以及为其他客户端进行设置。

本地 MCP 服务

获取 API 密钥

1. 从 API Portal 获取 Perplexity API 密钥
2. 将以下配置中的 your_key_here 替换为你的 API 密钥
3. （可选）设置超时时间：PERPLEXITY_TIMEOUT_MS=600000（默认值：5 分钟）
4. （可选）设置自定义基础 URL：PERPLEXITY_BASE_URL=https://your-custom-url.com（默认值：https://api.perplexity.ai）
5. （可选）设置日志级别：PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR（默认值：ERROR）

Claude Code

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

也可以通过插件安装：

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

Agent 插件

此仓库打包为 Agent Plugin，因此支持此标准的客户端可以直接从此仓库安装。Agent Plugins 格式不包含密钥，因此请通过客户端的插件或 MCP 设置来设置 PERPLEXITY_API_KEY 环境变量。

其他 MCP 客户端

大多数客户端都可以在客户端配置中使用相同的 mcpServers 包装格式进行手动配置（如 Cursor 所示）。如果客户端使用不同的架构，请查阅其文档，了解确切的包装格式。

手动设置时，以下客户端都使用相同的 mcpServers 结构：

客户端	配置文件
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"
      }
    }
  }
}

代理设置（适用于企业网络）

如果你在工作场所运行此服务，尤其是在公司防火墙或代理后方，可能需要告知程序如何通过网络代理发送互联网流量。请按以下步骤操作：

1. 获取代理信息

• 向 IT 部门询问 HTTPS 代理地址和端口。
• 你可能还需要用户名和密码。

2. 设置代理环境变量

对于 Perplexity MCP，最简单可靠的方式是使用 PERPLEXITY_PROXY。例如：

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

如果代理需要用户名和密码，请使用：

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

3. 替代方式：标准环境变量

如果你更愿意使用标准变量，我们也支持 HTTPS_PROXY 和 HTTP_PROXY。

说明

服务按以下顺序检查代理设置：PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY。如果均未设置，则会直接连接互联网。 URL 必须包含 https://。常见端口有 8080、3128 和 80。

自托管 HTTP 模式

对于云端或共享部署，请以 HTTP 模式运行服务。

环境变量

变量	描述	默认值
PERPLEXITY_API_KEY	你的 Perplexity API 密钥	必填
PERPLEXITY_BASE_URL	API 请求的自定义基础 URL	https://api.perplexity.ai
PORT	HTTP 服务端口	8080
BIND_ADDRESS	要绑定的网络接口。默认绑定到环回地址。设置为 0.0.0.0 可在所有接口上公开服务。	127.0.0.1
ALLOWED_ORIGINS	CORS 来源（逗号分隔）。默认为空（不允许跨源浏览器请求）。设置为明确的允许列表（例如 https://app.example.com），或设置为 * 以允许任何来源。	（空）
ALLOWED_HOSTS	允许的其他 Host 标头值（逗号分隔）。始终允许 PORT 上的环回主机。绑定到 0.0.0.0 时，请添加公共主机名。	（仅环回地址）

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

服务可通过 http://localhost:8080/mcp 访问

可用工具

perplexity_search

搜索结果会在可用时包含发布日期和最后更新日期。缺失或为 null 的日期会从格式化输出中省略。

使用 Perplexity Search API 直接进行网络搜索。返回带有元数据的排序搜索结果，非常适合查找最新信息。支持时效筛选（search_recency_filter）、域名限制（search_domain_filter），以及可降低延迟和成本的 Fast Search（search_type: "fast"）。

perplexity_ask

由 Agent API fast 预设驱动的通用对话式 AI，支持实时网络搜索。非常适合快速提问和日常搜索。

perplexity_research

由 Agent API high 预设驱动的深入、全面研究。适用于透彻分析和详细报告。运行可能需要几分钟；服务端会持续传输运行状态，并向请求状态的客户端报告进度。

perplexity_reason

由 Agent API medium 预设驱动的高级推理和问题解决。非常适合复杂的分析任务。

perplexity_ask 和 perplexity_reason 可接受可选的正整数 max_tokens（搜索上下文总量，最高为 120,000）和 max_tokens_per_page（每个结果页面的上下文量，最高为 20,000）。这些 Agent API 预算控制检索到的搜索内容，而非生成的回答长度。省略时，将沿用预设中的搜索配置。

仍接受旧版参数 search_context_size，但会在本地将其转换为明确的预算，而不会发送给 Agent API：

旧版大小	总 token 数	每页 token 数
low	2000	512
medium	4000	1024
high	8000	2048

此兼容策略与 Sonar 的命名大小并非完全等效；Agent API 迁移指南 中没有对应的命名大小。每个明确设置的预算都会覆盖相应的旧版默认值。

说明

预设是由 Perplexity 持续调优的托管配置（模型、搜索设置、步骤预算）；请参阅预设指南。此服务端的早期版本调用旧版 sonar-pro、sonar-reasoning-pro 和 sonar-deep-research 模型，并接受 strip_thinking / reasoning_effort 参数。这些参数已不再属于工具架构，发送时会被忽略；Agent API 不会生成 <think> 标签。

作为库使用

此软件包还导出了服务端工厂，可嵌入你自己的 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,
});

将返回的服务端挂载到任意 MCP 传输方式（stdio、可流式传输的 HTTP、内存中）。

故障排除

• API 密钥问题：确保已正确设置 PERPLEXITY_API_KEY
• 连接错误：检查网络连接和 API 密钥是否有效
• 未找到工具：确保已安装软件包且命令路径正确
• 超时错误：对于耗时很长的研究查询，请将 PERPLEXITY_TIMEOUT_MS 设置为更高的值
• 代理问题：检查 PERPLEXITY_PROXY 或 HTTPS_PROXY 配置，并确保防火墙未阻止 api.perplexity.ai。
• EOF / 初始化错误：某些严格的 MCP 客户端会因 npx 将安装消息写入 stdout 而失败。请使用 npx -yq，而非 npx -y，以禁止此输出。

如需支持，请访问 community.perplexity.ai 或提交问题。

---