kt-mcp-bc 0.3.0

Buyer-scoped MCP server for Keitaro Tracker — analytics-only access (clicks, conversions, reports) filtered by sub_id_3 = buyer_id.

Keitaro MCP — Buyer Edition

MCP-сервер для доступа к твоей аналитике в Keitaro Tracker из Claude Code и Claude Desktop. Видишь только данные своего трафика (по sub_id_3 = buyer_id), чужие кампании и конфиг трекера недоступны.

Что получишь

Четыре инструмента в Claude:

Инструмент	Что делает
keitaro_list_instances	список подключённых трекеров
keitaro_build_report	аналитические отчёты (метрики × дименшины × фильтры)
keitaro_get_clicks	сырые клики
keitaro_get_conversions	сырые конверсии

Все запросы автоматически фильтруются по твоему buyer_id. Подмена sub_id_3 блокируется до выхода на wire.

---

1. Что подготовить (один раз)

1.1 Установить uv

uv — менеджер Python-окружений, нужен для запуска сервера.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Проверь: uv --version должно отдать номер версии.

1.2 Получить у админа трекера 4 значения

Переменная	Что это	Где взять
KEITARO_URL	URL трекера, без слэша в конце	у админа, пример: https://tracker.example.com
KEITARO_API_KEY	твой API-ключ	админ создаёт в Maintenance → Users → твой логин → API keys
KEITARO_LOGIN	твой логин в Keitaro в точности как в колонке "Логін" (со всеми пробелами и пайпами)	у админа в Users, пример: TEAM | FB1 | ivanov
KEITARO_BUYER_ID	значение, которое летит в sub_id_3 на твоём трафике	у админа

1.3 Скачать MCP-сервер

git clone https://github.com/okosenko-commits/kt-mcp-buyercentric.git ~/kt-mcp-buyercentric
cd ~/kt-mcp-buyercentric
uv sync

Папка может быть любой, главное запомни абсолютный путь — он понадобится дальше.

---

2. Подключение к Claude Code (терминал)

В любой папке выполни:

claude mcp add keitaro -s user \
  -e "KEITARO_URL=https://tracker.example.com" \
  -e "KEITARO_API_KEY=<твой_ключ>" \
  -e "KEITARO_LOGIN=<твой_логин_как_в_keitaro>" \
  -e "KEITARO_BUYER_ID=<твой_buyer_id>" \
  -- uv --directory ~/kt-mcp-buyercentric run python -m keitaro_mcp

Флаг -s user сохранит конфиг в ~/.claude.json — он будет доступен из любой cwd. Если хочешь поднять только в конкретном проекте — замени на -s project и запусти команду из корня проекта (запишется в <project>/.mcp.json).

Проверь подключение:

claude mcp get keitaro

Ожидаемый вывод:

Status: ✓ Connected

Перезапусти Claude Code (если был запущен) — новые MCP-сервера подхватываются только при старте сессии. Теперь в чате можно писать естественным языком:

Покажи мои кампании за последнюю неделю с группировкой по странам, сортировка по revenue

Claude сам вызовет нужный инструмент.

---

3. Подключение к Claude Desktop (приложение)

Открой config-файл:

macOS:

open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Linux:

nano ~/.config/Claude/claude_desktop_config.json

Если файл пустой — вставь полностью:

{
  "mcpServers": {
    "keitaro": {
      "command": "uv",
      "args": [
        "--directory", "/АБСОЛЮТНЫЙ/путь/к/kt-mcp-buyercentric",
        "run", "python", "-m", "keitaro_mcp"
      ],
      "env": {
        "KEITARO_URL": "https://tracker.example.com",
        "KEITARO_API_KEY": "<твой_ключ>",
        "KEITARO_LOGIN": "<твой_логин_как_в_keitaro>",
        "KEITARO_BUYER_ID": "<твой_buyer_id>"
      }
    }
  }
}

Если уже есть другие MCP-сервера — добавь блок "keitaro": { ... } внутрь существующего mcpServers.

⚠️ Путь должен быть абсолютный. ~ в JSON не раскрывается. На macOS обычно /Users/<имя>/kt-mcp-buyercentric.

Сохрани файл и полностью выйди из Claude Desktop (Cmd+Q на macOS / закрыть через трей на Windows). Запусти заново. В чате должны появиться keitaro_* инструменты.

---

4. Где хранятся твои креденшалы

Клиент	Файл	Формат
Claude Code	~/.claude.json	plain JSON
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json	plain JSON
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json	plain JSON
Claude Desktop (Linux)	~/.config/Claude/claude_desktop_config.json	plain JSON

Ключи лежат в открытом виде на твоём диске. Никаких облаков, шифрования или Keychain. Файлы доступны только твоему системному пользователю (права 600/644). Если делишь компьютер с кем-то — учти.

В памяти процесса MCP api_key хранится только в одном объекте KeitaroClient и никогда не возвращается через keitaro_list_instances — наружу видны name / url / login / buyer_id / description.

---

5. Что MCP видит и не видит

✅ Видит:

• Клики и конверсии с sub_id_3 равным твоему buyer_id
• Все стандартные метрики Keitaro: clicks, conversions, revenue, profit, roi, cr, epc, cpc, cpa, leads, sales, bot_share и др.
• Все дименшины: campaign, offer, landing, country, device_type, browser, os, day, hour, sub_id_1..30 и др.

🚫 Не видит / не может:

• Данные других buyer-ов
• Конфигурацию трекера: список всех кампаний / офферов / лендингов / доменов / трафик-источников
• Создание / редактирование / удаление чего-либо

Если попросишь "покажи все кампании трекера" — Claude вернёт ошибку. Спроси иначе: "покажи мои кампании за неделю" — он сделает отчёт с группировкой по campaign, и ты увидишь только те, где был твой трафик.

---

6. Troubleshooting

Status: ✗ Failed to connect

Запусти сервер вручную в терминале и посмотри лог:

KEITARO_URL=https://... \
KEITARO_API_KEY=... \
KEITARO_LOGIN="..." \
KEITARO_BUYER_ID=... \
uv --directory ~/kt-mcp-buyercentric run python -m keitaro_mcp

Чтобы выйти — Ctrl+C.

Что искать в выводе:

Сообщение	Что значит	Что делать
Missing required env vars: ...	пропущена переменная	проверь все 4
HTTP 401 ... Invalid API key	ключ битый или истёк	взять у админа новый
Login '...' not found among Keitaro users	логин не совпал с тем что в трекере	проверь точное написание (пробелы, пайпы)
api_key OK | login NOT verified	это не ошибка — у тебя user-level ключ, MCP не может строго сверить логин, но ключ работает	продолжай работать
[<name>] login OK: <login> (USER/ADMIN)	строгая проверка прошла, всё ок	продолжай работать

"uv: command not found"

uv не в PATH. На macOS добавь в ~/.zshrc:

export PATH="$HOME/.local/bin:$PATH"

И перезапусти терминал.

Claude Code не видит keitaro-тулы

Перезапусти сессию (exit → claude снова, или Ctrl+C если открыт интерактивный режим). MCP-сервера подхватываются только при старте.

"Claude говорит что не может вызвать keitaro_list_campaigns"

By design. В buyer-edition доступны только 4 аналитических инструмента. Все запросы на конфиг трекера и CRUD блокируются. Если нужно «список кампаний» — спроси "кампании по которым у меня шёл трафик" — Claude использует keitaro_build_report с группировкой по campaign.

---

7. Несколько трекеров (опционально)

Если работаешь с двумя+ трекерами, замени env-vars на путь к JSON-файлу:

claude mcp add keitaro -s user \
  -e "KEITARO_CONFIG_FILE=$HOME/keitaro-instances.json" \
  -- uv --directory ~/kt-mcp-buyercentric run python -m keitaro_mcp

Файл ~/keitaro-instances.json:

[
  {
    "name": "main",
    "url": "https://main.tracker.com",
    "api_key": "...",
    "login": "...",
    "buyer_id": "...",
    "description": "Основной"
  },
  {
    "name": "test",
    "url": "https://test.tracker.com",
    "api_key": "...",
    "login": "...",
    "buyer_id": "...",
    "description": "Тестовый"
  }
]

В чате после этого можно явно указывать: "отчёт из инстанса test за вчера".

---

8. Обновление

cd ~/kt-mcp-buyercentric
git pull

Перезапусти Claude Code/Desktop — он автоматически подхватит новый код. Переустанавливать ничего не надо.

---

9. Удаление

Claude Code:

claude mcp remove keitaro -s user

Claude Desktop: удали блок "keitaro": { ... } из claude_desktop_config.json и перезапусти приложение.

Папку ~/kt-mcp-buyercentric можно потом просто стереть.