modelcontextprotocol README

项目的 README,来自 github.com/perplexityai/modelcontextprotocol。合并为一个 markdown 文件:README.md。

Perplexity API Platform MCP Server

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

The official MCP server implementation for the Perplexity API Platform, providing AI assistants with real-time web search, reasoning, and research capabilities through the Agent API and the Search API.

Remote MCP Server

The remote MCP server is hosted by Perplexity and is the easiest way to get started: same tools, nothing to install or update. The Cursor and VS Code buttons at the top of this page connect to it with one click. If your MCP client does not support remote servers yet, skip to the local server setup below. Connect over Streamable HTTP with your Perplexity API key:

https://api.perplexity.ai/mcp

For Claude Code:

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

See the MCP integration docs for manual Cursor/VS Code configuration, usage from the Anthropic API, and setup for other clients.

Local MCP Server

Get Your API Key

  1. Get your Perplexity API Key from the API Portal
  2. Replace your_key_here in the configurations below with your API key
  3. (Optional) Set timeout: PERPLEXITY_TIMEOUT_MS=600000 (default: 5 minutes)
  4. (Optional) Set custom base URL: PERPLEXITY_BASE_URL=https://your-custom-url.com (default: https://api.perplexity.ai)
  5. (Optional) Set log level: PERPLEXITY_LOG_LEVEL=DEBUG|INFO|WARN|ERROR (default: ERROR)

Claude Code

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

Or install 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

Agent Plugins

This repository is packaged as an Agent Plugin, so clients that support the standard can install it directly from this repository. The Agent Plugins format does not carry secrets, so set the PERPLEXITY_API_KEY environment variable through your client's plugin or MCP settings.

Other MCP Clients

Most clients can be configured manually using the same mcpServers wrapper in their client config (as shown for Cursor). If a client has a different schema, check its docs for the exact wrapper format.

For manual setup, these clients all use the same mcpServers structure:

Client Config File
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"
      }
    }
  }
}

Proxy Setup (For Corporate Networks)

If you are running this server at work—especially behind a company firewall or proxy—you may need to tell the program how to send its internet traffic through your network's proxy. Follow these steps:

1. Get your proxy details

2. Set the proxy environment variable

The easiest and most reliable way for Perplexity MCP is to use PERPLEXITY_PROXY. For example:

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

If your proxy needs a username and password, use:

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

3. Alternate: Standard environment variables

If you'd rather use the standard variables, we support HTTPS_PROXY and HTTP_PROXY.

[!NOTE] The server checks proxy settings in this order: PERPLEXITY_PROXY → HTTPS_PROXY → HTTP_PROXY. If none are set, it connects directly to the internet. URLs must include https://. Typical ports are 8080, 3128, and 80.

Self-Hosted HTTP Mode

For cloud or shared deployments, run the server in HTTP mode.

Environment Variables

Variable Description Default
PERPLEXITY_API_KEY Your Perplexity API key Required
PERPLEXITY_BASE_URL Custom base URL for API requests https://api.perplexity.ai
PORT HTTP server port 8080
BIND_ADDRESS Network interface to bind to. Defaults to loopback. Set to 0.0.0.0 to expose on all interfaces. 127.0.0.1
ALLOWED_ORIGINS CORS origins (comma-separated). Defaults to empty (no cross-origin browser requests). Set to an explicit allowlist (e.g. https://app.example.com) or to * to allow any origin. (empty)
ALLOWED_HOSTS Additional Host header values to accept (comma-separated). Loopback hosts on PORT are always allowed. Add the public hostname when binding to 0.0.0.0. (loopback only)

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

The server will be accessible at http://localhost:8080/mcp

Available Tools

perplexity_search

Search results include publication and last-updated dates when available. Missing or null dates are omitted from the formatted output.

Direct web search using the Perplexity Search API. Returns ranked search results with metadata, perfect for finding current information. Supports recency filters (search_recency_filter), domain restrictions (search_domain_filter), and Fast Search (search_type: "fast") for lower latency and cost.

perplexity_ask

General-purpose conversational AI with real-time web search, backed by the Agent API fast preset. Great for quick questions and everyday searches.

perplexity_research

Deep, comprehensive research backed by the Agent API high preset. Ideal for thorough analysis and detailed reports. Runs can take minutes; the server streams the run and reports progress to clients that request it.

perplexity_reason

Advanced reasoning and problem-solving backed by the Agent API medium preset. Perfect for complex analytical tasks.

perplexity_ask and perplexity_reason accept optional positive-integer max_tokens (total search context, up to 120,000) and max_tokens_per_page (context per result page, up to 20,000). These Agent API budgets control retrieved search content, not generated answer length. When omitted, the preset's search configuration remains in effect.

The legacy search_context_size argument is still accepted, but is translated locally into explicit budgets rather than sent to the Agent API:

Legacy size Total tokens Tokens per page
low 2000 512
medium 4000 1024
high 8000 2048

This compatibility policy is not an exact equivalent of Sonar's named sizes; the Agent API migration guide has no named-size equivalent. Each explicit budget overrides its corresponding legacy default.

[!NOTE] Presets are managed configurations (model, search setup, step budget) that Perplexity keeps tuned over time; see the presets guide. Earlier versions of this server called the legacy sonar-pro, sonar-reasoning-pro, and sonar-deep-research models and accepted strip_thinking / reasoning_effort parameters. Those parameters are no longer part of the tool schemas and are ignored if sent; the Agent API produces no <think> tags.

Use as a Library

The package also exports the server factory for embedding in your own Node process:

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,
});

Mount the returned server on any MCP transport (stdio, streamable HTTP, in-memory).

Troubleshooting

For support, visit community.perplexity.ai or file an issue.


modelcontextprotocol (perplexityai/modelcontextprotocol)

正在搜索数据库…

这是什么?这是 Perplexity API 平台的官方 MCP 服务器,通过 Perplexity 的 Agent API 和 Search API,为 AI 助手提供实时网络搜索、推理和研究工具。
这是独立应用,还是需要接入我的 AI 助手的组件?它是一个 MCP(Model Context Protocol,模型上下文协议)服务器,是一种连接器。任何兼容 MCP 的客户端(Claude Code、Cursor、VS Code、Codex、Claude Desktop)都可以与它通信,既可以通过 Perplexity 托管的远程端点使用,也可以运行在本地或自行部署的实例上。
我该怎么让它跑起来?最简单的方式是使用 Perplexity 托管的远程服务器,无需安装,只要用你的 API 密钥通过 Streamable HTTP 连接即可(Cursor/VS Code 有一键添加按钮)。如果要本地部署,可以在 Claude Code、Codex 或任何使用相同 mcpServers 配置结构的客户端中添加它(例如 ~/.cursor/mcp.json)。
我需要 Perplexity API 密钥吗?需要。请从 Perplexity API Portal 获取密钥,并将其设置为 PERPLEXITY_API_KEY(或直接填入客户端的 MCP 配置中)。
旧的 Sonar 模型和参数怎么了?早期版本会调用 sonar-pro、sonar-deep-research 等旧模型,并接受 strip_thinking、reasoning_effort 参数;现在这些参数会被忽略。服务器改为使用 Agent API 预设运行。旧的 search_context_size 值则会转换为 token 预算,不再直接发送给 API。
它实际提供了哪些工具?共四个:perplexity_search 用于直接的排序网页搜索,支持按时效和域名过滤;perplexity_ask 用于快速的对话式搜索(Agent API 的 fast 预设);perplexity_research 用于耗时数分钟的深度研究,并支持进度流式输出(high 预设);perplexity_reason 用于复杂的分析任务(medium 预设)。
我能为团队自行部署,而不使用 Perplexity 的托管端点吗?可以,通过 Docker 或 Node.js 以 HTTP 模式运行,并使用 PORT、BIND_ADDRESS、ALLOWED_ORIGINS 和 ALLOWED_HOSTS 来控制网络暴露范围和 CORS。
我能把它嵌入自己的应用,而不是作为单独的服务器运行吗?可以,该包导出了一个服务器工厂函数,你可以在自己的 Node 进程中将其挂载到任何 MCP 传输方式上(stdio、streamable HTTP、内存中)。
它能在企业代理后面使用吗?可以,它会先检查 PERPLEXITY_PROXY,然后回退到标准的 HTTPS_PROXY/HTTP_PROXY 变量;如果都未设置,则直接连接。
大小
1.1 MB
星标
2.6K
更新
提交Oct 21
时长
1年
提交 · 90 天