使用说明

困惑MCP服务器

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

特性

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

开发环境

适用于Claude Code用户

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

使用容器（仅限Claude代码）

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

仅使用容器：所有文件操作、代码编辑和shell命令都必须使用容器使用环境执行
查看您的作品：更改后，通知其他人如何访问您的作品：
- 使用 container-use log <env_id> 查看开发日志
- 使用 container-use checkout <env_id> 检查您的环境
无本地操作：不要直接在本地文件系统上执行文件操作

示例开发工作流程（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 <your-env-id>
container-use checkout <your-env-id>

这确保了在使用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:

```bash
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/

配置说明

路径配置：替换 /path/to/perplexica-mcp/ 安装的实际路径
令人困惑的URL：确保 PERPLEXICA_BACKEND_URL 指向您正在运行的Perplexica实例
运输选择:
- 使用标准适用于大多数MCP客户端（Claude Desktop、Cursor）
- 使用 上海证券交易所 适用于基于web的客户端或实时应用程序
- 使用 超文本传输协议 用于REST API集成
依赖项：确保 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 << 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初始化请求
上海证券交易所 `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执行人工智能网络搜索。

参数：

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传输
✓ 符合流式HTTP规范的HTTP传输
✓ SSE传输端点可访问性

运输详情

标准运输

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

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

服务器发送事件以进行实时通信
端点： http://host:port/sse
包括用于连接健康状况的定期ping消息

可流式HTTP传输

符合MCP流式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许可证获得许可-有关详细信息，请参阅许可证文件。

贡献

分叉存储库
创建功能分支（如果使用Claude Code，则使用容器使用环境）
进行更改（如果使用Claude Code，则在容器使用环境中）
如果适用，添加测试
提交拉取请求
如果使用Claude Code，请通过以下方式访问您的作品 container-use log <env_id> 和 container-use checkout <env_id>

支持

对于问题和疑问：

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