Perplexity MCP

🚀 Perplexity MCP 服務器

Perplexity MCP 服務器是一個模型上下文協議（MCP）服務器，它將 Perplexity AI 的搜索增強語言模型與 Claude Desktop 集成，提供了三種複雜度遞進的工具，以滿足不同的使用場景。

✨ 主要特性

🔍 三種複雜度級別

• perplexity_small：使用 sonar - pro 模型進行快速查詢。
• perplexity_medium：使用 sonar - reasoning - pro 模型增強推理能力。
• perplexity_large：使用 sonar - deep - research 模型進行深度研究。

🚀 專為開發優化

• 乾淨的響應：自動去除思考標記。
• 全面的錯誤處理。
• 詳細的日誌記錄，便於調試。
• 基於 FastMCP 構建，可靠性高。

🔧 現代 Python 技術棧

• 使用 UV 進行快速依賴管理。
• 使用 HTTPX 實現現代 HTTP 客戶端功能。
• 代碼庫中廣泛使用類型提示。
• 擁有全面的測試套件。

🚀 快速開始

前提條件

• Python 3.11 及以上版本。
• UV 包管理器。
• Perplexity API 密鑰。
• Claude Desktop。

安裝步驟

1. 克隆倉庫

   git clone <repository-url>
   cd Perplexity_MCP
   

2. 安裝依賴

   uv sync
   

3. 設置環境

   echo "PERPLEXITY_API_KEY=your_api_key_here" > .env
   

4. 測試安裝

   uv run python tests/tests.py small
   

Claude Desktop 集成

1. 查找 UV 路徑

   which uv
   # 示例輸出：/Users/username/.local/bin/uv
   

2. 配置 Claude Desktop 編輯 ~/Library/Application Support/Claude/claude_desktop_config.json：

   {
     "mcpServers": {
       "perplexity-mcp": {
         "command": "/Users/username/.local/bin/uv",
         "args": [
           "--directory", 
           "/path/to/your/Perplexity_MCP",
           "run",
           "python",
           "server.py"
         ]
       }
     }
   }
   

3. 重啟 Claude Desktop 完全退出並重新啟動 Claude Desktop 以加載新的 MCP 服務器。

💻 使用示例

在 Claude Desktop 中使用

配置完成後，您可以在對話中使用這些工具：

基礎用法

Use perplexity_small to find: "What is the latest Python version?"

高級用法

Use perplexity_medium to explain: "Compare REST vs GraphQL performance characteristics"

Use perplexity_large to research: "Comprehensive analysis of quantum computing trends in 2024"

工具規格

響應格式

所有工具都返回乾淨、結構化的響應：

{
  "content": "The AI response with thinking tokens removed",
  "citations": ["https://source1.com", "https://source2.com"]
}

📚 詳細文檔

項目結構

Perplexity_MCP/
├── server.py                # 包含 3 個工具的 FastMCP 服務器
├── client.py                # Perplexity API 包裝器  
├── config.py                # 配置和工具設置
├── __init__.py              # 包導出
├── pyproject.toml           # UV 項目配置
├── tests/
│   ├── tests.py             # 單個工具的測試腳本
│   └── test_logs/           # 測試結果和日誌
└── Notes/
    ├── explanations.md      # 技術深入分析
    └── questions.txt        # 開發問題

運行測試

測試單個工具以驗證 API 集成：

# 獨立測試每個工具
uv run python tests/tests.py small    # 測試 sonar - pro 模型
uv run python tests/tests.py medium   # 測試 sonar - reasoning - pro
uv run python tests/tests.py large    # 測試 sonar - deep - research（運行時間長）

# 結果保存到 tests/test_logs/ 並進行詳細的響應分析

開發設置

1. 安裝開發依賴

   uv sync --all-groups
   

2. 在本地運行 MCP 服務器（用於調試）

   uv run python server.py
   

3. 檢查代碼質量

   uv run ruff check .
   uv run black .
   

配置

環境變量

工具配置

工具在 config.py 中進行配置：

TOOL_CONFIGS = {
    "small": {
        "model": "sonar-pro"
    },
    "medium": {
        "model": "sonar-reasoning-pro", 
        "reasoning_effort": "medium",
        "web_search_options": {"search_context_size": "medium"}
    },
    "large": {
        "model": "sonar-deep-research",
        "reasoning_effort": "high",
        "web_search_options": {"search_context_size": "high"}
    }
}

故障排除

常見問題

導入錯誤

ModuleNotFoundError: No module named 'client'

• 確保您從項目根目錄運行。
• 檢查 UV 是否使用了正確的虛擬環境。

API 密鑰問題

Error: PERPLEXITY_API_KEY environment variable is required

• 驗證 .env 文件是否存在幷包含 API 密鑰。
• 檢查 API 密鑰在 Perplexity 設置頁面 上是否有效。

Claude Desktop 連接問題

• 驗證配置中的 UV 路徑：which uv。
• 確保項目目錄路徑是絕對且正確的。
• 檢查 Claude Desktop 日誌以獲取具體錯誤消息。
• 配置更改後完全重啟 Claude Desktop。

響應時間過長

• perplexity_large 對於複雜查詢可能需要 10 - 30 分鐘。
• 使用 perplexity_small 或 perplexity_medium 以獲得更快的響應。
• 選擇工具時考慮查詢的複雜度。

調試模式

通過直接運行服務器啟用詳細日誌記錄：

uv run python server.py
# 檢查 stderr 輸出以獲取詳細的日誌信息

測試單個組件

# 測試 API 連接
uv run python -c "from client import PerplexityClient; print('✅ Client OK')"

# 測試配置
uv run python -c "from config import get_api_key; print('✅ API Key OK')"

# 測試服務器啟動
timeout 10s uv run python server.py || echo "Server started successfully"

🤝 貢獻代碼

1. 分叉倉庫。
2. 創建功能分支：git checkout -b feature-name。
3. 進行更改並進行全面測試。
4. 根據需要更新文檔。
5. 提交拉取請求。

開發指南

• 遵循現有的代碼風格（Black 格式化、類型提示）。
• 為新功能添加測試。
• 對任何架構更改更新 CLAUDE.md。
• 使用所有三種 Perplexity 模型進行測試。
• 確保符合 MCP 協議（乾淨的 stdout）。

🔧 技術細節

關鍵設計決策

• 基於類的客戶端：使用單例模式進行高效的資源管理。
• 思考標記移除：自動過濾 <think>...</think> 部分。
• 簡化響應：僅包含內容和引用，便於乾淨集成。
• 錯誤隔離：不將異常傳播到 MCP 層。
• 日誌策略：所有調試輸出到 stderr 以符合 MCP 協議。

依賴項

• mcp>=1.11.0 - 帶有 FastMCP 的 MCP Python SDK。
• python-dotenv>=1.1.1 - 環境變量管理。
• httpx>=0.28.1 - 帶有超時處理的現代 HTTP 客戶端。

📄 許可證

MIT 許可證 - 詳情請參閱 LICENSE 文件。

🙏 致謝

• Perplexity AI 提供強大的搜索增強語言模型。
• Anthropic 提供 Claude 和 MCP 協議。
• FastMCP 提供優秀的 MCP 框架。

🛠️ 支持

• API 問題：Perplexity 支持。
• MCP 協議問題：MCP 文檔。
• Claude Desktop 問題：Claude 支持。

⚠️ 重要提示

此 MCP 服務器目前針對本地開發和個人使用進行了優化。未來版本可能會提供 PyPI 分發選項，以便更輕鬆地安裝和共享。