Skip to main content
Glama
perplexity-unofficial-mcp

perplexity-unofficial-mcp

by exqlnet

Perplexity Unofficial MCP(基于 Cookies)

非官方实现:本项目通过浏览器 Cookies 调用 Perplexity 的 Web 接口,稳定性与合规性不做保证。请确保你的使用方式符合你所在组织的安全要求与 Perplexity 的服务条款。

本项目目标是把非官方 perplexity-ai(Python SDK,Cookies 方式)包装成一个 MCP STDIO Server,让 MCP 客户端(Claude Desktop / Cursor / VS Code 等)能像使用官方 Perplexity MCP 一样使用它。

你会得到什么

  • 一个 Python MCP Server(STDIO + JSON-RPC 2.0),工具命名对齐官方:

    • perplexity_ask

    • perplexity_research

    • perplexity_reason

    • perplexity_search

  • 一份可直接用于 MCP 客户端的快速配置 JSON

Related MCP server: PPX-MCP

前置条件

  • Python >= 3.10

  • uv 已安装(https://docs.astral.sh/uv/)

  • 非官方 SDK 依赖:

    • 默认通过 pyproject.toml 里的 git pin 依赖安装(见 perplexity-api @ git+https://...@<commit>)

    • 因此运行环境通常需要可用的 git 与网络访问(受限网络环境可考虑自行改为 vendoring)

  • (可选)你已在浏览器登录 Perplexity,并能获取 Cookies(提供后通常更稳定;未提供时可能走匿名访问/自动回退,取决于 Perplexity 侧策略)

重要:STDIO 模式下 stdout 只能输出 MCP 协议消息。本项目所有日志都输出到 stderr。建议使用 uv -q 并设置 UV_NO_PROGRESS=1 来尽量抑制 uv 自身输出。

Cookies 获取与配置

获取 Cookies(建议方式)

  1. 在浏览器登录 perplexity.ai

  2. 打开开发者工具 → Application/Storage → Cookies → https://www.perplexity.ai

  3. 找到并复制你当前会话的 Cookies(常见包含):

    • next-auth.csrf-token

    • next-auth.session-token

通过两个环境变量传入 Cookies(推荐方式)

本项目默认使用两个环境变量注入 Cookies:

  • PERPLEXITY_CSRF_TOKEN:对应 next-auth.csrf-token

  • PERPLEXITY_SESSION_TOKEN:对应 next-auth.session-token

如果上述变量缺失或为空,服务端会自动生成随机占位值用于满足上游 SDK 的参数形态(不会写入 stdout/stderr)。此时是否能成功调用取决于 Perplexity 是否允许匿名访问及其回退策略,本项目不做稳定性保证。

注意:不要把 token 写进仓库或公开渠道;建议通过本机环境变量或密钥管理注入。

安装与启动(推荐:uv)

本项目不再提供或依赖 npx 启动方式。推荐使用 uv 直接运行(由 uv 负责依赖解析与运行)。

如果你需要把它接入 MCP 客户端,推荐使用“从 GitHub 仓库地址启动”的形式(无需本地 clone)。

MCP 快速配置(JSON)

以下示例默认使用主分支 main。生产/团队环境建议 pin 到 tag 或 commit 以保证可复现。

Cursor / Claude Desktop / Windsurf(mcpServers 格式)

方式:使用 uv 从 GitHub 启动(推荐)

{
  "mcpServers": {
    "perplexity_unofficial": {
      "command": "uv",
      "args": [
        "-q",
        "tool",
        "run",
        "--from",
        "git+https://github.com/exqlnet/unofficial-perplexity-mcp.git@main",
        "perplexity-unofficial-mcp"
      ],
      "env": {
        "PERPLEXITY_CSRF_TOKEN": "<csrf>",
        "PERPLEXITY_SESSION_TOKEN": "<session>",
        "UV_NO_PROGRESS": "1",
        "UV_COLOR": "never"
      }
    }
  }
}

VS Code(.vscode/mcp.json,servers 格式)

方式:使用 uv 从 GitHub 启动(推荐)

{
  "servers": {
    "perplexity_unofficial": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "-q",
        "tool",
        "run",
        "--from",
        "git+https://github.com/exqlnet/unofficial-perplexity-mcp.git@main",
        "perplexity-unofficial-mcp"
      ],
      "env": {
        "PERPLEXITY_CSRF_TOKEN": "<csrf>",
        "PERPLEXITY_SESSION_TOKEN": "<session>",
        "UV_NO_PROGRESS": "1",
        "UV_COLOR": "never"
      }
    }
  }
}

工具说明(与官方对齐)

perplexity_ask

  • 入参:query(字符串),可选 backend_uuid

  • 行为:

    • 为避免调用方误传导致行为不可预测:本 MCP 已禁用外部 mode / model 入参

    • 服务端会按内部默认策略选择模式(例如有 Cookies 时倾向使用 pro,并默认使用 gpt-5.2)

    • 请避免频繁调用;尽量将多个子问题合并到一次 query / 一次 perplexity_search 中查清楚

  • 出参:content(文本)+ structuredContent.response(文本)+ 可选 structuredContent.chunks + 可选 structuredContent.backend_uuid

续问(同一对话线程继续问)

  • 每次调用若上游返回 backend_uuid,本 MCP 会在 structuredContent.backend_uuid 回传。

  • 下一次调用时,把该值作为入参 backend_uuid 传回,即可让 Perplexity 以同一对话上下文续问。

  • 注意:该能力依赖网页端私有接口与服务端策略,backend_uuid 可能缺失、过期或被忽略;本项目不保证稳定。

perplexity_research

  • 入参:query(字符串),可选 backend_uuid、strip_thinking

  • 行为:

    • 默认 deep research(专用语义)

    • 本 MCP 已禁用外部 mode / model 入参

    • 注意:这是重型调用,耗时更长;仅在必要时使用,优先 ask/search

perplexity_reason

  • 入参:query(字符串),可选 backend_uuid、strip_thinking

  • 行为:

    • 默认 reasoning(专用语义)

    • 本 MCP 已禁用外部 mode / model 入参

  • 入参:query(字符串),可选 backend_uuid

  • 行为:

    • 当前实现返回“回答文本”(并尽量在 structuredContent.chunks 附带结构化片段)

    • 本 MCP 已禁用外部 mode / model 入参;服务端会按内部默认策略选择模式

    • 请避免频繁调用;尽量把要查的点写进一次 query(例如用编号列出多个子问题),一次 search 查清楚

说明:官方 perplexity_search 语义是“返回搜索结果列表”;非官方 SDK 不一定稳定提供同等结构,因此本实现优先保证可用性与对齐接口形状。

重要:本 MCP 不再支持 messages[] 入参;如果你的调用方仍传 messages,会返回工具级错误并提示改用 query。 重要:本 MCP 不再支持 mode / model 入参;如果你的调用方仍传 mode / model,会返回工具级错误并提示移除该字段。

排错

  • 启动报错 未找到 uv:安装 uv 后重试。

  • 提示 Cookies 无效/请求失败:通常是会话过期,重新获取 Cookies 并更新 PERPLEXITY_CSRF_TOKEN / PERPLEXITY_SESSION_TOKEN。

  • MCP 客户端初始化失败:检查是否有任何非协议输出写入 stdout;本项目日志写入 stderr,且推荐使用 uv -q 并设置 UV_NO_PROGRESS=1,仍失败时请检查你的外层启动命令是否会向 stdout 输出额外内容。

  • GitHub 拉取失败:检查网络与 git 可用性;受限环境可改为本地 clone 后再使用本地方式启动(见下文开发说明)。

开发说明

直接运行(不走 uv)

在仓库目录下:

  • 使用 PYTHONPATH=src python3 -m perplexity_unofficial_mcp.cli(适合不安装依赖时做协议层开发)

  • 使用 uv -q run --no-editable perplexity-unofficial-mcp(会按 pyproject.toml 安装依赖)

安全提示

  • 不要把真实 Cookies 提交到 git、截图或粘贴到公开渠道。

  • 建议通过密钥管理(或本机环境变量注入)提供 PERPLEXITY_CSRF_TOKEN / PERPLEXITY_SESSION_TOKEN。

Available Tools

4 tools
perplexity_askAsk PerplexityB
Read-only

对齐官方 Perplexity MCP:输入 query 字符串并返回回答文本。请避免频繁调用;尽量将多个子问题合并到一次 query / 一次 perplexity_search 中查清楚。

Inputs: query (required), backend_uuid.

perplexity_reasonAdvanced ReasoningC
Read-only

对齐官方 Perplexity MCP:推理(默认 reasoning)。请避免频繁调用;尽量将多个子问题合并到一次 query / 一次 perplexity_search 中查清楚。

Inputs: query (required), backend_uuid, strip_thinking.

perplexity_researchDeep Research(重型)A
Read-only

对齐官方 Perplexity MCP:深度研究(重型调用,耗时更长;仅在必要时使用,优先 ask/search)。请避免频繁调用;尽量将多个子问题合并到一次 query / 一次 perplexity_search 中查清楚。

Inputs: query (required), backend_uuid, strip_thinking.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 4 tools

    Disambiguation2/5

    All four tools take a query and return answer text, with nearly identical boilerplate warnings about avoiding frequent calls. The boundaries between perplexity_ask and perplexity_search are especially unclear since search also returns answer text, and only perplexity_research (heavy) and perplexity_reason (reasoning) are somewhat distinct.

    Naming Consistency5/5

    Every tool follows the exact same perplexity_<action> snake_case pattern with no deviations. The naming is fully predictable and consistent.

    Tool Count5/5

    Four tools align with the four Perplexity modes (ask, search, reason, research), which is a well-scoped set for a wrapper. No obvious missing or redundant tools based on the stated purpose.

    Completeness4/5

    The surface covers the main query modes, but perplexity_search returns answer text rather than fully structured search results, and there is no explicit conversational/session tool. These are minor gaps that agents can likely work around.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An unofficial MCP server for Perplexity AI that leverages Pro subscriptions and browser cookies to enable real-time web searches and model selection without an API key. It provides tools for performing queries, listing available models, and automating the login process to manage authentication.
      4
      30 npm
      MIT
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      A Python port of the official Perplexity MCP server that enables web-grounded Q\&A, deep research, and step-by-step reasoning via Perplexity AI's models. It supports both STDIO and HTTP interfaces for seamless integration with tools like Claude Desktop and Cursor.
      MIT