使用说明

唯一具有多帐户池、管理仪表板和零成本监控的Perplexity MCP服务器。
没有API密钥。没有每次查询的费用。使用现有的困惑专业会话。

特性 · 快速开始 · 管理面板 · 配置 · 建筑

🎯 为什么是这个？

大多数困惑MCP服务器都是围绕付费Sonar API的单帐户包装器。 这次不一样：

🆓 无API成本 -使用会话cookie，而不是付费API。功能相同，每次查询费用为零
🏊 多账户池 --具有自动故障转移功能的N个帐户之间的循环
📊 管理员仪表板 --React UI实时监控配额、管理代币、尾日志
❤️ 零成本健康检查 -通过rate-limit API监控所有帐户，而不使用查询
🛡️ 降级保护 --检测困惑何时无声地返回常规结果，而不是深入研究
📱 电报警报 --令牌过期或配额用完时收到通知

✨ 特性

🔍 智能搜索

专业搜索 --快速、准确的答案和引用
推理 --复杂决策的多模型思维
深入研究 --全面的10-30+引文报告
多源 --网络、学者与社会

🤖 9种型号可供选择

sonar · gpt-5.2 · claude-4.5-sonnet · grok-4.1
gpt-5.2-thinking · claude-4.5-sonnet-thinking
gemini-3.0-pro · kimi-k2-thinking · grok-4.1-reasoning

🏊 令牌池引擎

循环跨账户轮换
指数退避 关于失败（60年代→ 120s → ... → 1h上限）
三级回退 --专业→ 汽车（耗尽）→ 匿名
智能配额跟踪 --本地递减，验证为零
热重载 --在不重新启动的情况下添加/删除令牌

🛡️ 生产硬化

静默式深度研究降级检测
原子配置保存（崩溃时无损坏）
连接中断处理
通过跨进程状态共享 pool_state.json
53个单元测试

🖼️ 截图

令牌池仪表板

_{统计网格、监控控件、带有每个帐户配额的可排序令牌表（Pro/Research/Agentic）、过滤药丸和一键操作。}

日志查看器

_{实时日志流，具有自动刷新、级别过滤、搜索突出显示、关注模式和行号功能。}

🚀 快速开始

1.克隆和安装

git clone https://github.com/teoobarca/perplexity-mcp.git
cd perplexity-mcp
uv sync

2.添加到您的AI工具

🟣 Claude Code

claude mcp add perplexity -s user -- uv --directory /path/to/perplexity-mcp run perplexity-mcp

🟢 Cursor

首选 设置→ MCP → 添加新服务器 并粘贴：

{
  "command": "uv",
  "args": ["--directory", "/path/to/perplexity-mcp", "run", "perplexity-mcp"]
}

🔵 Windsurf / VS Code / Other MCP clients

添加到MCP配置文件中：

{
  "mcpServers": {
    "perplexity": {
      "command": "uv",
      "args": ["--directory", "/path/to/perplexity-mcp", "run", "perplexity-mcp"]
    }
  }
}

就这样 立即使用匿名会话。添加您的Pro访问令牌——请参阅认证.

🛠️ 工具

两个MCP工具具有LLM优化的描述，因此您的AI助手会自动选择正确的一个：

`perplexity_ask`

人工智能驱动的答案引擎，用于技术问题、文档查找和操作指南。

参数	类型	默认值	说明
`query`	字符串	必需的	带有语境的自然语言问题
`model`	字符串	`null`	型号选择（参见模型)
`sources`	阵列	`["web"]`	来源： `web`, `scholar`, `social`
`language`	字符串	`en-US`	ISO 639语言代码

模式自动检测： 模型与 thinking 或 reasoning 在名称中自动切换到 推理模式.

"gpt-5.2"          → Pro Search
"gpt-5.2-thinking"  → Reasoning Mode  ← auto-detected

`perplexity_research`

深入研究，全面分析。返回10-30+引用的广泛报告。

参数	类型	默认值	说明
`query`	字符串	必需的	具有完整背景的详细研究问题
`sources`	阵列	`["web", "scholar"]`	来源： `web`, `scholar`, `social`
`language`	字符串	`en-US`	ISO 639语言代码

[！提示] 深入研究每个查询需要2-5分钟。提供详细的上下文和约束条件，以获得更好的结果。服务器有15分钟的超时时间来适应这种情况。

🖥️ 管理面板

一个内置的网络仪表板，用于管理您的代币池。从以下内容开始：

perplexity-server

在以下位置自动打开 http://localhost:8123/admin/

特性	描述
📊 统计网格	客户总数、在线/已用电量、监视器状态
📋 令牌表	可排序列、过滤药丸（在线/耗尽/离线/未知）、图标操作
💰 配额栏	按代币细分——专业剩余、研究配额、代理研究
❤️ 健康监视器	通过速率限制API进行零成本检查，可配置间隔
📱 电报警报	令牌状态更改通知（过期、耗尽、重新联机）
🔄 回退切换	启用/禁用自动Pro→ 自由回退
📥 导入/导出	通过JSON配置文件进行批量令牌管理
📝 日志查看器	直播、级别过滤器（错误/警告/信息/调试）、搜索、关注模式
🧪 测试按钮	对单个令牌或一次对所有令牌运行健康检查

🔐 认证

默认情况下，服务器使用 匿名困惑会话 （价格有限）。对于Pro访问，请添加您的会话令牌。

如何获取代币

登录地址：困惑.ai
打开 开发者工具 （F12）→ 应用 → Cookie
复制这两个cookie：
- next-auth.csrf-token
- next-auth.session-token

单一代币

创建 token_pool_config.json 在项目根目录中：

{
  "tokens": [
    {
      "id": "my-account",
      "csrf_token": "your-csrf-token-here",
      "session_token": "your-session-token-here"
    }
  ]
}

多令牌池

添加多个帐户轮转具有自动故障转移功能：

{
  "monitor": {
    "enable": true,
    "interval": 6,
    "tg_bot_token": "optional-telegram-bot-token",
    "tg_chat_id": "optional-chat-id"
  },
  "fallback": {
    "fallback_to_auto": true
  },
  "tokens": [
    { "id": "account-1", "csrf_token": "...", "session_token": "..." },
    { "id": "account-2", "csrf_token": "...", "session_token": "..." },
    { "id": "account-3", "csrf_token": "...", "session_token": "..." }
  ]
}

[！注意] 会话令牌持续约30天。监视器检测过期的令牌并通过Telegram向您发出警报。

⚙️ 配置

环境变量

变量	默认值	描述
`PERPLEXITY_TIMEOUT`	`900`	请求超时（秒）（深度研究为15分钟）
`SOCKS_PROXY`	--	SOCKS5代理URL(`socks5://host:port`)

令牌状态

令牌状态根据以下内容自动计算 session_valid + rate_limits （切勿手动设置）：

状态	含义	徽章	行为
🟢 `normal`	会话有效，支持配额	在线的	用于所有请求
🟡 `exhausted`	会话有效，专业配额=0	精疲力竭	Pro跳过，用作自动回退
🔴 `offline`	会话无效/已过期	离线	不用于任何请求
🔵 `unknown`	尚未检查	未知	正常使用（假设配额可用）

后备链

当Pro请求失败时，服务器会逐步尝试：

1. ✅ Next client with Pro quota (round-robin)
2. ✅ Next client with Pro quota ...
3. 🟡 Any available client (auto mode)
4. 🔵 Anonymous session (auto mode)
5. ❌ Error returned to caller

🏗️ 建筑

┌─────────────────────────────────────────────────────────┐
│  Your AI Assistant (Claude Code / Cursor / Windsurf)    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP (stdio)
                       ▼
┌──────────────────────────────────────────────────────────┐
│  perplexity-mcp                                          │
│  ┌────────────────┐  ┌────────────────────────────────┐  │
│  │  tools.py       │  │  server.py                     │  │
│  │  • ask          │──│  • Pool state sync             │  │
│  │  • research     │  │  • Timeout handling            │  │
│  └────────────────┘  └────────────────────────────────┘  │
└──────────────────────┬───────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────┐
│  Backend Engine (perplexity/)                            │
│                                                          │
│  ┌─────────────┐  ┌──────────────┐  ┌────────────────┐  │
│  │  client.py   │  │  client_pool │  │  admin.py      │  │
│  │  • Search    │  │  • Rotation  │  │  • REST API    │  │
│  │  • Upload    │  │  • Backoff   │  │  • Static      │  │
│  │  • Validate  │  │  • Monitor   │  │    files       │  │
│  └──────┬───────┘  │  • Fallback  │  └────────┬───────┘  │
│         │          └──────────────┘           │          │
│         ▼                                     ▼          │
│  ┌─────────────┐                    ┌────────────────┐   │
│  │ Perplexity  │                    │ React Admin UI │   │
│  │ (web API)   │                    │ :8123/admin/   │   │
│  └─────────────┘                    └────────────────┘   │
└──────────────────────────────────────────────────────────┘

组件	文件	角色
MCP服务器	`src/server.py`	标准传输、池状态同步、超时处理
工具定义	`src/tools.py`	2个MCP工具，具有LLM优化的描述
API客户端	`perplexity/client.py`	通过curl_cffi的困惑API（绕过Cloudflare）
客户端池	`perplexity/server/client_pool.py`	循环、退避、监视、状态持久性
查询引擎	`perplexity/server/app.py`	旋转循环、三级回退、验证
管理员API	`perplexity/server/admin.py`	REST端点+静态文件服务
管理用户界面	`perplexity/server/web/`	React+Vite+顺风仪表板

🧪 发展

# Install in development mode
uv pip install -e ".[dev]" --python .venv/bin/python

# Run unit tests (53 tests)
.venv/bin/python -m pytest tests/ -v

# Frontend development
cd perplexity/server/web
npm install
npm run dev      # Dev server with proxy to :8123
npm run build    # Production build

项目结构

src/                          # MCP stdio server (thin wrapper)
  server.py                   #   Entry point, pool state sync
  tools.py                    #   Tool definitions

perplexity/                   # Backend engine
  client.py                   #   Perplexity API client (curl_cffi)
  config.py                   #   Constants, endpoints, model mappings
  exceptions.py               #   Custom exception hierarchy
  logger.py                   #   Centralized logging
  server/
    app.py                    #   Starlette app, query engine
    client_pool.py            #   ClientPool, rotation, monitor
    admin.py                  #   Admin REST API
    utils.py                  #   Validation helpers
    main.py                   #   HTTP server entry point
    web/                      #   React admin frontend (Vite + Tailwind)

tests/                        # 53 unit tests

⚠️ 局限性

非官方 --使用Perplexity的web界面，如果更改，可能会损坏
基于Cookie的身份验证 --会话令牌将在约30天后过期
费率限制 --匿名会话具有严格的查询限制
深入研究 --每次查询需要2-5分钟（这是正常的）

📄 许可证

麻省理工学院