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

前置条件

• 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 入参

perplexity_search

• 入参：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。