Perplexica MCP Server

Perplexica MCP 服务

一个使用 Perplexica 的 AI 搜索引擎提供搜索功能的模型上下文协议（MCP）服务。

功能

• 搜索工具：AI 驱动的搜索，支持多种来源类型（网络、学术、讨论）
• 支持多种传输方式：stdio、SSE 和 Streamable HTTP 传输
• FastMCP 集成：使用 FastMCP 构建，确保稳健遵循 MCP 协议
• 统一架构：单一服务实现，支持所有传输模式
• 可用于生产环境：支持 Docker，并遵循安全最佳实践

开发环境

Claude Code 用户须知

重要提示：如果你使用 Claude Code 进行开发，本项目要求所有开发操作都必须使用 container-use MCP 服务。所有文件操作、代码修改和 Shell 命令都必须在 container-use 环境中执行。

使用 Container-Use（仅限 Claude Code）

使用 Claude Code 为本项目做贡献时，你必须：

1. 仅使用 Container-Use：所有文件操作、代码编辑和 Shell 命令都必须通过 container-use 环境执行
2. 查看你的工作：完成修改后，告知他人如何访问你的工作：
   • 使用 container-use log <env_id> 查看开发日志
   • 使用 container-use checkout <env_id> 检出你的环境
3. 不得在本地操作：不要直接在本地文件系统上执行文件操作

开发工作流示例（Claude Code）

# Create a new environment for your work
container-use create --title "Your feature description"

# Make your changes using container-use tools
# (All file operations handled by container-use)

# Share your work with others
container-use log <your-env-id>
container-use checkout <your-env-id>

使用 Claude Code 时，这能确保所有开发活动的一致性、可复现性，并正确进行版本控制。

适用于其他开发环境

如果你不使用 Claude Code，可以使用自己偏好的工具和 IDE 正常开发。常规开发工作流不受 container-use 要求的限制。

安装

从 PyPI 安装（推荐）

# Install directly from PyPI
pip install perplexica-mcp

# Or using uvx for isolated execution
uvx perplexica-mcp --help

从源代码安装

# Clone the repository
git clone https://github.com/thetom42/perplexica-mcp.git
cd perplexica-mcp

# Install dependencies
uv sync

MCP 客户端配置

要将此服务与 MCP 客户端搭配使用，需要配置客户端以连接 Perplexica MCP 服务。以下是常见 MCP 客户端的配置示例。

重要提示：所有传输模式都需要正确配置环境变量，尤其是：

• PERPLEXICA_BACKEND_URL：Perplexica 后端 API 的 URL
• PERPLEXICA_CHAT_MODEL_PROVIDER 和 PERPLEXICA_CHAT_MODEL_NAME：聊天模型配置
• PERPLEXICA_EMBEDDING_MODEL_PROVIDER 和 PERPLEXICA_EMBEDDING_MODEL_NAME：嵌入模型配置

必须在环境中设置这些变量，或在 MCP 客户端配置中提供这些变量。

Claude Desktop

Stdio 传输（推荐）

将以下内容添加到 Claude Desktop 配置文件中：

位置：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）

{
  "mcpServers": {
    "perplexica": {
      "command": "uvx",
      "args": ["perplexica-mcp", "stdio"],
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

替代方式（从源代码运行）：

{
  "mcpServers": {
    "perplexica": {
      "command": "uv",
      "args": ["run", "python", "-m", "perplexica_mcp", "stdio"],
      "cwd": "/path/to/perplexica-mcp",
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

注意：从源代码运行时，请确保已设置所有必需的环境变量。stdio 传输需要正确配置模型提供商和模型名称，才能与 Perplexica 后端通信。

#### SSE Transport

For SSE transport, first start the server:

```bash
uv run src/perplexica_mcp/server.py sse

然后配置 Claude Desktop：

{
  "mcpServers": {
    "perplexica": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Cursor IDE

添加到 Cursor MCP 配置中：

{
  "servers": {
    "perplexica": {
      "command": "uvx",
      "args": ["perplexica-mcp", "stdio"],
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

替代方式（从源代码运行）：

{
  "servers": {
    "perplexica": {
      "command": "uv",
      "args": ["run", "python", "-m", "perplexica_mcp", "stdio"],
      "cwd": "/path/to/perplexica-mcp",
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

VS Code（使用 MCP 扩展）

添加到 VS Code MCP 配置文件（.vscode/mcp.json）中：

{
  "servers": {
    "perplexica": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "perplexica_mcp", "stdio"],
      "cwd": "/path/to/perplexica-mcp",
      "env": {
        "PERPLEXICA_BACKEND_URL": "http://localhost:3000/api/search",
        "PERPLEXICA_CHAT_MODEL_PROVIDER": "openai",
        "PERPLEXICA_CHAT_MODEL_NAME": "gpt-4o-mini",
        "PERPLEXICA_EMBEDDING_MODEL_PROVIDER": "openai",
        "PERPLEXICA_EMBEDDING_MODEL_NAME": "text-embedding-3-small"
      }
    }
  }
}

通用 MCP 客户端配置

适用于支持 stdio 传输的任何 MCP 客户端：

# Command to run the server (PyPI installation)
uvx perplexica-mcp stdio

# Command to run the server with .env file (PyPI installation)
uvx --env-file .env perplexica-mcp stdio

# Command to run the server (from source)
uv run python -m perplexica_mcp stdio

# Environment variables (can be exported or set inline)
export PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search
export PERPLEXICA_CHAT_MODEL_PROVIDER=openai
export PERPLEXICA_CHAT_MODEL_NAME=gpt-4o-mini
export PERPLEXICA_EMBEDDING_MODEL_PROVIDER=openai
export PERPLEXICA_EMBEDDING_MODEL_NAME=text-embedding-3-small

# Or set inline for single execution (all required vars)
PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search \
PERPLEXICA_CHAT_MODEL_PROVIDER=openai \
PERPLEXICA_CHAT_MODEL_NAME=gpt-4o-mini \
PERPLEXICA_EMBEDDING_MODEL_PROVIDER=openai \
PERPLEXICA_EMBEDDING_MODEL_NAME=text-embedding-3-small \
uvx perplexica-mcp stdio

适用于 HTTP/SSE 传输的客户端：

# Start the server (PyPI installation)
uvx perplexica-mcp sse  # or 'http'

# Start the server (from source)
uv run /path/to/perplexica-mcp/src/perplexica_mcp/server.py sse  # or 'http'

# Connect to endpoints
SSE: http://localhost:3001/sse
HTTP: http://localhost:3002/mcp/

配置说明

1. 路径配置：将 /path/to/perplexica-mcp/ 替换为实际安装路径
2. Perplexica URL：确保 PERPLEXICA_BACKEND_URL 指向正在运行的 Perplexica 实例
3. 传输方式选择：
   • 大多数 MCP 客户端（Claude Desktop、Cursor）使用 stdio
   • 基于 Web 的客户端或实时应用使用 SSE
   • REST API 集成使用 HTTP
4. 依赖项：确保已安装 uvx 并且可在 PATH 中使用（源码安装则使用 uv）

故障排除

• 服务无法启动：检查是否已安装 uvx（源码安装则检查 uv），并确认路径正确
• 连接被拒绝：确认 Perplexica 正在运行，且可通过配置的 URL 访问
• 权限错误：确保 MCP 客户端有权限执行服务命令
• 环境变量：检查是否已正确设置 PERPLEXICA_BACKEND_URL

服务配置

在项目根目录创建 .env 文件，配置 Perplexica：

# Perplexica Backend Configuration
PERPLEXICA_BACKEND_URL=http://localhost:3000/api/search

# Default Model Configuration (Optional)
# If set, these models will be used as defaults when no model is specified in the search request

# Chat Model Configuration
PERPLEXICA_CHAT_MODEL_PROVIDER=openai
PERPLEXICA_CHAT_MODEL_NAME=gpt-4o-mini

# Embedding Model Configuration  
PERPLEXICA_EMBEDDING_MODEL_PROVIDER=openai
PERPLEXICA_EMBEDDING_MODEL_NAME=text-embedding-3-small

环境变量

变量	描述	默认值	示例
PERPLEXICA_BACKEND_URL	Perplexica 搜索 API 的 URL	http://localhost:3000/api/search	http://localhost:3000/api/search
PERPLEXICA_CHAT_MODEL_PROVIDER	默认聊天模型提供商	无	openai、ollama、anthropic
PERPLEXICA_CHAT_MODEL_NAME	默认聊天模型名称	无	gpt-4o-mini、claude-3-sonnet
PERPLEXICA_EMBEDDING_MODEL_PROVIDER	默认嵌入模型提供商	无	openai、ollama
PERPLEXICA_EMBEDDING_MODEL_NAME	默认嵌入模型名称	无	text-embedding-3-small

注意：模型环境变量是可选的。如果未设置，则需要在每个搜索请求中指定模型。设置后，这些变量会提供便捷的默认值，但仍可按请求覆盖。

使用方法

该服务支持三种传输模式：

1. Stdio 传输

# PyPI installation
uvx perplexica-mcp stdio

# From source
uv run src/perplexica_mcp/server.py stdio

2. SSE 传输

# PyPI installation
uvx perplexica-mcp sse [host] [port]

# From source
uv run src/perplexica_mcp/server.py sse [host] [port]
# Default: localhost:3001, endpoint: /sse

3. Streamable HTTP 传输

# PyPI installation
uvx perplexica-mcp http [host] [port]

# From source
uv run src/perplexica_mcp/server.py http [host] [port]
# Default: localhost:3002, endpoint: /mcp

Docker 部署

该服务支持 Docker，可使用多种传输配置进行容器化部署。

前提条件

• 已安装 Docker 和 Docker Compose
• 外部 Docker 网络，名称为 backend（用于与 Perplexica 集成）

创建外部网络

docker network create backend

构建并运行

选项 1：HTTP 传输（Streamable HTTP）

# Build and run with HTTP transport
docker-compose up -d

# Or build first, then run
docker-compose build
docker-compose up -d

选项 2：SSE 传输（服务器发送事件）

# Build and run with SSE transport
docker-compose -f docker-compose-sse.yml up -d

# Or build first, then run
docker-compose -f docker-compose-sse.yml build
docker-compose -f docker-compose-sse.yml up -d

环境配置

两种 Docker 配置均支持环境变量：

# Create .env file for Docker
cat > .env << EOF
PERPLEXICA_BACKEND_URL=http://perplexica-app:3000/api/search
EOF

# Uncomment env_file in docker-compose.yml to use .env file

也可以直接在 compose 文件中设置环境变量：

environment:
  - PERPLEXICA_BACKEND_URL=http://your-perplexica-host:3000/api/search

容器详情

传输方式	容器名称	端口	端点	健康检查
HTTP	perplexica-mcp-http	3001	/mcp/	MCP 初始化请求
SSE	perplexica-mcp-sse	3001	/sse	SSE 端点检查

健康监控

两个容器都包含健康检查：

# Check container health
docker ps
docker-compose ps

# View health check logs
docker logs perplexica-mcp-http
docker logs perplexica-mcp-sse

与 Perplexica 集成

Docker 配置假定 Perplexica 正在同一 Docker 网络中运行：

# Example Perplexica service in the same compose file
services:
  perplexica-app:
    # ... your Perplexica configuration
    networks:
      - backend
  
  perplexica-mcp:
    # ... MCP server configuration
    environment:
      - PERPLEXICA_BACKEND_URL=http://perplexica-app:3000/api/search
    networks:
      - backend

生产环境注意事项

• 两个容器都使用 restart: unless-stopped，以确保可靠运行
• 健康检查可确保服务可用
• 外部网络支持与现有 Perplexica 部署集成
• Dockerfile 中实施了安全最佳实践

可用工具

搜索

使用 Perplexica 执行 AI 驱动的网页搜索。

参数：

• query（字符串，必填）：搜索查询
• sources（数组，必填）：要使用的搜索来源。有效值："web"、"academic"、"discussions"。可组合多个来源。
• chat_model（对象，可选）：聊天模型配置
• embedding_model（对象，可选）：嵌入模型配置
• optimization_mode（字符串，可选）："speed"、"balanced" 或 "quality"
• history（数组，可选）：对话历史，格式为 [["human", "text"], ["assistant", "text"]] 对
• system_instructions（字符串，可选）：自定义指令
• stream（布尔值，可选）：是否以流式方式传输响应

测试

运行全面的测试套件以验证所有传输方式：

uv run src/test_transports.py

这将测试：

• ✓ 使用 MCP 协议握手的 Stdio 传输
• ✓ 符合 Streamable HTTP 规范的 HTTP 传输
• ✓ SSE 传输端点的可访问性

传输详情

Stdio 传输

• 使用 FastMCP 内置的 Stdio 服务
• 支持完整的 MCP 协议，包括初始化和工具列表
• 适用于 MCP 客户端集成

SSE 传输

• 使用 Server-Sent Events 实现实时通信
• 端点：http://host:port/sse
• 定期发送 ping 消息以检查连接状态

Streamable HTTP 传输

• 符合 MCP Streamable HTTP 规范
• 端点：http://host:port/mcp
• 按照协议返回 307 重定向到 /mcp/
• 使用 StreamableHTTPSessionManager 妥善处理会话

开发

此服务使用以下组件构建：

• FastMCP：现代 MCP 服务框架，内置传输支持
• Uvicorn：用于 SSE 和 HTTP 传输的 ASGI 服务
• httpx：用于与 Perplexica API 通信的 HTTP 客户端
• python-dotenv：环境变量管理

架构

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│ Perplexica MCP   │◄──►│   Perplexica    │
│                 │    │     Server       │    │   Search API    │
│  (stdio/SSE/    │    │   (FastMCP)      │    │                 │
│   HTTP)         │    │                  │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌──────────────┐
                       │   FastMCP    │
                       │  Framework   │
                       │ ┌──────────┐ │
                       │ │  stdio   │ │
                       │ │   SSE    │ │
                       │ │  HTTP    │ │
                       │ └──────────┘ │
                       └──────────────┘

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

贡献

1. Fork 此代码仓库
2. 创建功能分支（如果使用 Claude Code，请使用 container-use 环境）
3. 进行修改（如果使用 Claude Code，请在 container-use 环境中操作）
4. 如适用，请添加测试
5. 提交拉取请求
6. 如果使用 Claude Code，请通过 container-use log <env_id> 和 container-use checkout <env_id> 提供对你工作的访问权限

支持

如有问题或疑问：

• 查看故障排除部分
• 查阅 Perplexica 文档
• 在 GitHub 上提交问题