tavily-mcp-proxy

Reverse-прокси для эндпоинта Tavily MCP, который:

1. Обходит гео-блокировку для клиентов на IP из санкционных территорий (RU и др.) — прокси живёт на VPS в стране, откуда Tavily доступен, и пересылает запросы.

2. Ротирует несколько Tavily API-ключей, выбирая раз в сутки ключ с наибольшим остатком квоты. Если ни один ключ не удалось проверить — прокси возвращает HTTP 503 всем клиентам (fail-loud) до восстановления.

3. Аутентифицирует клиентов по query-параметру accessKey, чтобы реальные Tavily-ключи никогда не попадали на клиентские машины и не светились в клиентских конфигах.

┌──────────┐    ?accessKey=tvmcp_…     ┌─────────────┐    ?tavilyApiKey=<active>    ┌────────┐
│  Клиент  │ ────────────────────────► │    nginx    │ ───────────────────────────► │ Tavily │
└──────────┘     TLS + fail2ban        │    (TLS)    │                              └────────┘
                                       └─────┴───────┘
                                             │ http://127.0.0.1:8741
                                             ▼
                         ┌────────────────────────────────────────┐
                         │      tavily-mcp-backend (aiohttp)      │
                         │          • проверяет accessKey         │
                         │   • подставляет активный Tavily-ключ   │
                         │         • стримит SSE upstream         │
                         └────────────────────────────────────────┘
                                   ежедневно в 05:00 Europe/Moscow
                                             ▲
                         ┌────────────────────────────────────────┐
                         │            quota_checker.py            │
                         │       • GET /usage на каждый ключ      │
                         │       • атомарно пишет active-key      │
                         └────────────────────────────────────────┘

Состав репозитория

Related MCP server: tavily-mcp-proxy

Быстрый старт (TL;DR)

Полный runbook — в AGENTS.md. Самый короткий путь:

# На VPS (Ubuntu 24.04) — детали в AGENTS.md
apt-get install -y nginx certbot python3-certbot-nginx fail2ban python3-venv python3-pip

mkdir -p /etc/tavily-mcp /opt/tavily-mcp
# заполнить /etc/tavily-mcp/tavily-keys.list и access-keys.list (см. deploy/*.example)

cd /opt/tavily-mcp
python3 -m venv venv
venv/bin/pip install -r requirements.txt

cp deploy/tavily-mcp-backend.service deploy/tavily-mcp-quota.service \
   deploy/tavily-mcp-quota.timer /etc/systemd/system/
cp deploy/tavily-mcp.nginx.conf /etc/nginx/sites-available/tavily-mcp
# отредактировать YOUR-HOST.sslip.io в конфиге nginx, затем:
ln -sf /etc/nginx/sites-available/tavily-mcp /etc/nginx/sites-enabled/tavily-mcp
nginx -t && systemctl reload nginx

systemctl daemon-reload
systemctl enable --now tavily-mcp-backend tavily-mcp-quota.timer

Конфигурация MCP-клиента (OpenCode, Claude Desktop, MCP CLI и т.п.):

https://YOUR-HOST.sslip.io/mcp/?accessKey=tvmcp_<ваш-сгенерированный-ключ>

Конфигурационные файлы на сервере

active-key переписывается атомарно (tempfile → fsync → os.replace) скриптом quota_checker.py. Бэкенд читает файл на каждый запрос, поэтому переключение ключа происходит без рестарта.

Генерация access-ключа

python3 -c 'import secrets, base64; print("tvmcp_" + base64.urlsafe_b64encode(secrets.token_bytes(36)).decode().rstrip("="))'

После изменения /etc/tavily-mcp/access-keys.list:

kill -HUP $(pgrep -f backend.py)

…или перезапустить systemd-сервис.

Безопасность

• Реальные Tavily-ключи живут только на VPS (0600, root). Клиентам никогда не передаются.

• Реальные access-ключи (tvmcp_…) живут только на VPS и в клиентских конфигах под вашим контролем — не коммитьте их в публичные репозитории.

• Формат лога nginx mcp_nosecret не пишет query string, поэтому ни Tavily-ключи, ни access-ключи в access-логе не оседают.

• fail2ban банит IP-адрес источника перманентно через nftables-allports (подробности — в AGENTS.md → «Защита VPS»):

  • sshd: 5 неудачных SSH-логинов с одного IP за 24 ч → IP блокируется на всех TCP-портах.

  • nginx-scan: 1 запрос с IP к путям сканеров (.env, wp-admin, xmlrpc.php, phpmyadmin, …) → IP блокируется на всех TCP-портах.

  • tavily-mcp: 5 × HTTP 401 с одного IP на /mcp/ за 24 ч → IP блокируется на портах 80/443 (остальные порты работают).

  • Порт 22 (SSH) не банится ни в одном джейле — зайти по SSH можно всегда, в том числе чтобы разбанить себя. Разбан вручную: ssh vps 'fail2ban-client unban <забаненный-IP>'.

  • Самобан — критично: 5 неудачных SSH-попыток (протухший ключ в ssh-agent) или 1 случайный curl к пути сканера = ваш домашний IP уходит в перманентный бан → потеря доступа к VPS. Восстановление: мобильный хотспот / VPN / веб-консоль хостера (зайти с другого IP), затем fail2ban-client unban <свой-IP>.

HTTPS / домен

Прокси требует публичный HTTPS-эндпоинт. Полный runbook — в AGENTS.md → «Домен и сертификат» и «Восстановление с нуля»; здесь — короткая версия.

1. Wildcard-DNS через публичные сервисы. sslip.io и nip.io — это разные сервисы (НЕ зеркала друг друга), оба резолвят имя вида <IP-С-ДЕФИСАМИ>.<service>.io в IP, зашитый в имя. Регистрация в DNS не нужна.

2. Сертификат Let's Encrypt через certbot --nginx -d <YOUR-HOST>.sslip.io (HTTP-01 challenge на 80 порту). Файлы лежат в /etc/letsencrypt/live/<YOUR-HOST>.../. Срок действия — 90 дней (стандарт Let's Encrypt).

3. Автопродление — certbot.timer (systemd): каждые ~12 часов проверяет, осталось ли <15 дней до истечения, и автоматически перевыпускает сертификат (на практике — на 75-й день жизни). Порог задан в /etc/letsencrypt/renewal/<domain>.conf через renew_before_expiry = 15 days. Если таймер по какой-то причине не сработал — certbot renew вручную.

4. Когда LE упирается в rate-limit (5 сертификатов в неделю на один домен): сгенерировать имя <IP-С-ДЕФИСАМИ>.nip.io, получить сертификат для него, обновить server_name в nginx, обновить URL в MCP-клиенте. Это разные DNS-сервисы, поэтому для LE это разные домены — rate-limit sslip.io не действует на nip.io.

⚠️ Что ломает работу MCP-клиента

Имя <IP-С-ДЕФИСАМИ>.sslip.io привязано к конкретному IP-адресу VPS. Если IP VPS меняется (переустановка у хостера, смена тарифа, миграция), то:

• Резолв старого имени перестаёт указывать на новый IP.

• Старый сертификат остаётся валидным по дате, но для другого IP он бесполезен (TLS-хендшейк успешный, но клиент обращается к чужому IP).

• OpenCode (и любой MCP-клиент) перестаёт работать до тех пор, пока на клиентской машине не обновится URL на новое имя.

Порядок действий при смене IP: сгенерировать новое имя <НОВЫЙ-IP-С-ДЕФИСАМИ>.sslip.io (или .nip.io) → certbot --nginx -d <НОВОЕ-ИМЯ> на VPS → обновить mcp.tavily.url в ~/.config/opencode/opencode.jsonc на Mac → перезапустить сессию OpenCode. Полный чеклист — в AGENTS.md → Troubleshooting → «IP VPS сменился».

Имя хоста видно в публичных логах Certificate Transparency — это нормально. Безопасность держится на секретности ключей (accessKey у клиентов, реальные Tavily-ключи — только на VPS).

Лицензия

MIT (заглушка — поменяйте по желанию).