Perplexica MCP Server

Perplexica MCP サーバー

Perplexica の AI 搭載検索エンジンを使用した検索機能を提供する Model Context Protocol（MCP）サーバーです。

機能

• 検索ツール：複数のソースタイプ（ウェブ、学術、ディスカッション）に対応した AI 搭載検索
• 複数のトランスポートに対応：stdio、SSE、Streamable HTTP トランスポート
• FastMCP との統合：堅牢な MCP プロトコル準拠を実現する FastMCP を使用して構築
• 統合アーキテクチャ：すべてのトランスポートモードに対応する単一のサーバー実装
• 本番環境対応：セキュリティのベストプラクティスに基づく Docker 対応

開発環境

Claude Code ユーザー向け

重要：Claude Code を開発に使用する場合、このプロジェクトではすべての開発作業に container-use MCP サーバーを使用する必要があります。すべてのファイル操作、コードの変更、シェルコマンドは、container-use 環境内で実行してください。

Container-Use の使用（Claude Code のみ）

Claude Code を使用してこのプロジェクトに貢献する場合、次の要件に従ってください。

1. Container-Use のみを使用：すべてのファイル操作、コード編集、シェルコマンドは 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 を使用してください
   • ウェブベースのクライアントやリアルタイムアプリケーションには 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

注意：モデルの環境変数は任意です。設定しない場合は、検索リクエストごとにモデルを指定する必要があります。設定すると、リクエストごとに上書き可能な便利なデフォルト値として使用できます。

使用方法

サーバーは 3 つのトランスポートモードに対応しています。

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. ストリーム可能な 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 トランスポート（Server-Sent Events）

# 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
• プロトコルに従い、/mcp/ への 307 リダイレクトを返します
• 適切なセッション処理のために 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. リポジトリをフォークします
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 でイシューを作成します