Perplexica MCP Server

困惑MCP服务器

一种模型上下文协议（MCP）服务器，使用Perplexica的人工智能搜索引擎提供搜索功能。

特性

• 搜索工具：具有多种来源类型（网络、学术、讨论）的人工智能搜索
• 多种运输支持：stdio、SSE和流式HTTP传输
• FastMCP集成：使用FastMCP构建，以实现强大的MCP协议合规性
• 统一架构：支持所有传输模式的单服务器实现
• 生产就绪：Docker支持与安全最佳实践

开发环境

适用于Claude Code用户

重要：如果您正在使用Claude Code进行开发，则此项目需要使用 container-use 用于所有开发操作的MCP服务器。所有文件操作、代码更改和shell命令都必须在容器使用环境中执行。

使用容器（仅限Claude代码）

使用Claude Code为该项目做出贡献时，您必须：

1. 仅使用容器：所有文件操作、代码编辑和shell命令都必须使用容器使用环境执行
2. 查看您的作品：更改后，通知其他人如何访问您的作品：

- 使用 container-use log 查看开发日志 - 使用 container-use checkout 检查您的环境

1. 无本地操作：不要直接在本地文件系统上执行文件操作

示例开发工作流程（Claude代码）

# 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 
container-use checkout 

这确保了在使用Claude Code时，所有开发活动的一致性、可重复性和适当的版本控制。

其他开发环境

如果你没有使用Claude Code，你可以使用你喜欢的工具和IDE正常开发。容器使用要求不适用于常规开发工作流程。

安装

来自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配置文件中：

位置: ~/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:

uv run src/perplexica_mcp/server.py sse

然后配置Claude Desktop：

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

### 光标IDE

添加到光标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代码（带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/` 安装的实际路径
1. **令人困惑的URL**：确保 `PERPLEXICA_BACKEND_URL` 指向您正在运行的Perplexica实例
1. **运输选择**:
   - 使用 **标准** 适用于大多数MCP客户端（Claude Desktop、Cursor）
   - 使用 **上海证券交易所** 适用于基于web的客户端或实时应用程序
   - 使用 **超文本传输协议** 用于REST API集成
1. **依赖项**：确保 `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` |困惑搜索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.标准运输

PyPI installation

uvx perplexica-mcp stdio

From source

uv run src/perplexica_mcp/server.py stdio

### 2.苏格兰和南方能源公司运输

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.流式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传输（流式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 和 container-use checkout `

支持

对于问题和疑问：

• 检查故障排除部分
• 查阅Perplexica文档
• 在GitHub上打开一个问题