Perplexity MCP 服务器

这是一个集成 Perplexity AI 的搜索增强型语言模型与 Claude Desktop 的 Model Context Protocol (MCP) 服务器，提供三种不同复杂度的工具以适应不同的使用场景。

特性

🔍 三种复杂度级别

• 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 中

配置完成后，你可以在对话中使用这些工具：

快速事实查询：

使用 perplexity_small 查找: "最新的 Python 版本是什么？"

技术分析：

使用 perplexity_medium 解释: "比较 REST 和 GraphQL 的性能特征"

深入研究：

使用 perplexity_large 研究: "2024 年量子计算趋势的全面分析"

工具规格

工具	模型	使用场景	响应时间	特性
perplexity_small	sonar-pro	快速事实、基本查询	约 3-10 秒	快速、可靠
perplexity_medium	sonar-reasoning-pro	技术解释	约 10-30 秒	增强推理
perplexity_large	sonar-deep-research	综合研究	约 5-30 分钟	深入分析、高质量

响应格式

所有工具返回干净、结构化的响应：

{
  "content": "已移除思考标记的 AI 响应",
  "citations": ["https://source1.com", "https://source2.com"]
}

开发

项目结构

Perplexity_MCP/
├── server.py                # 包含三个工具的 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 .
   

配置

环境变量

变量	必需	描述
PERPLEXITY_API_KEY	是	从 设置页面 获取的 Perplexity API 密钥

工具配置

工具在 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: 没有名为 'client' 的模块

• 确保你在项目根目录下运行
• 检查 UV 是否使用了正确的虚拟环境

API 密钥问题

错误: 需要 PERPLEXITY_API_KEY 环境变量

• 验证你的 .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('✅ 客户端正常')"

# 测试配置
uv run python -c "from config import get_api_key; print('✅ API 密钥正常')"

# 测试服务器启动
timeout 10s uv run python server.py || echo "服务器成功启动"

贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature-name
3. 修改并彻底测试
4. 如有必要更新文档
5. 提交拉取请求

开发指南

• 遵循现有代码风格（Black 格式化，类型提示）
• 新功能添加测试
• 更新 CLAUDE.md 以反映架构变化
• 使用所有三种 Perplexity 模型进行测试
• 确保符合 MCP 协议（干净的标准输出）

架构

关键设计决策

• 基于类的客户端：单例模式以高效管理资源
• 思考标记移除：自动过滤 <think>...</think> 部分
• 简化响应：仅包含内容和引用以实现干净集成
• 错误隔离：不向 MCP 层传播异常
• 日志策略：所有调试输出到 stderr 以符合 MCP 协议

依赖项

• mcp>=1.11.0 - MCP Python SDK，带 FastMCP
• 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 发布选项，以便更轻松地安装和分享。