io.github.ivanantigravity-lgtm/perplexity-polza-mcp-server

Perplexity MCP server backed by the Polza.ai chat completions API.

Open source Open in the app JSON README (API)

About

Perplexity MCP server backed by the Polza.ai chat completions API.

Details

Kind: MCP servers
Topic: Web search, scraping & browser
Publisher: ivanantigravity-lgtm
Origin: official
Category: ferramentas
Transport: local
Version: 0.1.1
Stars: 1
Forks: 1
Last push: 2026-04-22T11:03:14Z
Repository state: ativo
Language: Python
License: MIT
Added: 2026-08-29 04:00:12
Updated: 2026-08-29 04:00:12
Origin id: io.github.ivanantigravity-lgtm/perplexity-polza-mcp-server

README

# Perplexity MCP Server via Polza.ai

`mcp-name: io.github.ivanantigravity-lgtm/perplexity-polza-mcp-server`

MCP сервер для `Claude Desktop` и `Claude Code`, который ходит в модели Perplexity (`Sonar`, `Sonar Pro`, `Sonar Reasoning`, `Sonar Deep Research`) через агрегатор [Polza.ai](https://polza.ai).

## Что умеет

- `perplexity_model_guide` — шпаргалка по выбору модели под задачу
- `perplexity_ask` — обычный вопрос в Perplexity
- `perplexity_research` — более глубокий ресёрч с веб-поиском
- `list_perplexity_models` — список доступных `perplexity/*` моделей из каталога Polza

## Что нужно для установки

- `Claude Desktop` или `Claude Code` (или любой другой MCP-клиент)
- [`uv`](https://docs.astral.sh/uv/) (ставится одной командой, см. ниже)
- Python 3.11+
- `POLZA_AI_API_KEY` — ключ берётся на [polza.ai/dashboard/api-keys](https://polza.ai/dashboard/api-keys)

Поставить `uv`:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

## Установка за 2 минуты (через PyPI + uvx)

Это самый простой путь: ничего клонировать не надо, `uvx` сам скачает пакет из PyPI.

### Claude Code / VS Code

Создай файл `.mcp.json` в корне своего проекта:

```json
{
  "mcpServers": {
    "perplexity-polza": {
      "command": "uvx",
      "args": ["perplexity-polza-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here"
      }
    }
  }
}
```

Перезапусти Claude Code — готово.

### Claude Desktop (macOS)

Открой файл `~/Library/Application Support/Claude/claude_desktop_config.json` и добавь:

```json
{
  "mcpServers": {
    "perplexity-polza": {
      "command": "uvx",
      "args": ["perplexity-polza-mcp-server@latest"],
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here"
      }
    }
  }
}
```

Перезапусти Claude Desktop.

### Claude Desktop (Windows)

Файл: `%APPDATA%\Claude\claude_desktop_config.json`. Содержимое такое же, как на macOS.

## Как проверить, что работает

После перезапуска Claude попроси:

> Покажи доступные модели Perplexity через polza

Claude должен вызвать tool `list_perplexity_models` и вернуть список.

## Когда какую модель брать

- `Sonar` — быстрый поиск + ответ. Новости, факты, Q&A, короткие суммаризации.
- `Sonar Pro` — плотнее структура, сравнения, follow-up вопросы.
- `Sonar Pro Search` — глубже поиск, больше поисковых шагов.
- `Sonar Reasoning Pro` — не просто найти, а разобрать и сделать вывод.
- `Sonar Deep Research` — полноценный ресёрч, market scan, длинный отчёт.

Переключить дефолтную модель можно через переменные окружения `PERPLEXITY_MODEL` и `PERPLEXITY_RESEARCH_MODEL` — полный список ниже.

## Переменные окружения

| Переменная | Обязательная | По умолчанию | Описание |
| --- | --- | --- | --- |
| `POLZA_AI_API_KEY` | да | — | Ключ с polza.ai |
| `POLZA_BASE_URL` | нет | `https://polza.ai/api/v1` | Base URL для chat completions (с `/v1` — это ожидаемо, endpoint OpenAI-совместим) |
| `PERPLEXITY_MODEL` | нет | `perplexity/sonar` | Модель для `perplexity_ask` |
| `PERPLEXITY_RESEARCH_MODEL` | нет | `perplexity/sonar-deep-research` | Модель для `perplexity_research` |
| `LOG_LEVEL` | нет | `INFO` | — |

## Локальная разработка

```bash
git clone https://github.com/ivanantigravity-lgtm/perplexity-polza-mcp-server.git
cd perplexity-polza-mcp-server
uv sync
POLZA_AI_API_KEY=your_key uv run python -m perplexity_polza_mcp_server.server
```

Для локального подключения из source в Claude:

```json
{
  "mcpServers": {
    "perplexity-polza-local": {
      "command": "uv",
      "args": ["run", "python", "-m", "perplexity_polza_mcp_server.server"],
      "cwd": "/absolute/path/to/perplexity-polza-mcp-server",
      "env": {
        "POLZA_AI_API_KEY": "your-polza-api-key-here"
      }
    }
  }
}
```

## Под капотом

- Chat completions: `POST https://polza.ai/api/v1/chat/completions` (OpenAI-совместимый формат)
- Model catalog: `GET https://polza.ai/api/v1/models/catalog`

## Важные файлы в репозитории

- `pyproject.toml` — метаданные пакета и entry points
- `server.json` — описание для MCP Registry
- `fastmcp.json` — локальная конфигурация FastMCP
- `.github/workflows/publish-pypi.yml` — публикация в PyPI через GitHub Actions

## Лицензия

MIT.

io.github.ivanantigravity-lgtm/perplexity-polza-mcp-server

About

Details

README

More