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 分发选项，以便更轻松地安装和共享。