hamster-bot новинка: MCP

RU EN PT

Кто за что отвечает#

Путь одной команды: «закрой позицию по BTC»#

1. 1Человек пишет сообщение в приложении Claude. Оно уходит в облако Anthropic по HTTPS.
2. 2Claude Code на VPS сам опрашивает облако и забирает сообщение. Модель решает, какой инструмент вызвать.
3. 3Агент вызывает close_position на /mcp с токеном api_token. Бот проверяет токен.
4. 4MCP-сервер превращает вызов в обычный запрос к /api/* этого же бота и передаёт тот же токен. Поэтому логика и проверки у MCP и API одни.
5. 5API передаёт команду ядру бота. Ядро берёт ключ этого аккаунта.
6. 6Коннектор подписывает запрос и отправляет его на биржу. Результат идёт обратно по той же цепочке и появляется на телефоне.

Что будет, если одна из частей отключится#

Что агент может делать через MCP#

Из 87 инструментов 42 только читают данные (readOnlyHint), а 25 помечены как опасные (destructiveHint): они торгуют, запускают ботов или необратимо меняют данные. Это рыночные ордера, закрытие позиций, отмена ордеров, запуск ботов, сохранение и удаление стратегий и ключей, изменение конфига, выключение и обновление программы. Тестер работает на истории и с биржей не торгует.

Границы доступа#

• Токен даёт права владельца. С api_token доступны все 87 инструментов, включая торговлю, удаление аккаунтов и выключение программы. Режима только для чтения нет.
• Подтверждение зависит от клиента. Опасные инструменты только помечены, а спрашивать человека должен MCP-клиент. В автономном режиме разрешения выдаются заранее, и агент действует без вопросов.
• CLAUDE.md задаёт правила, но не защищает. Лимиты риска и запрет выходить за пределы папки агент соблюдает как инструкцию. Если у него есть shell под тем же пользователем, что и у бота, он технически может читать файлы бота.
• Токен не всегда нужен. Когда вход через Telegram выключен, запросы к /mcp с этой же машины проходят без токена. Это касается любого локального процесса.
• Веб-интерфейс, API и MCP работают на одном порту. Агенту на том же VPS хватает адреса 127.0.0.1. С другой машины токен идёт открытым текстом, поэтому через интернет нужен HTTPS-прокси или SSH-туннель.

Как это запускается на VPS#

1. В settings_program.json бота, перезапуск не нужен:

   Копировать

   "use_mcp": true

2. Сессия, которая переживёт закрытие SSH:

   Копировать

   tmux new -s agent

3. Подключить агента к боту:

   Копировать

   claude mcp add --transport http hamster-bot http://127.0.0.1:<порт>/mcp --header "Authorization: Bearer <api_token>"

4. Открыть сессию для телефона:

   Копировать

   claude remote-control --name "hamster-bot"

5. В чате сессии: автономная работа по расписанию:

   Копировать

   /loop 6h Продолжай работу по CLAUDE.md

Подключение: подробности#

По умолчанию MCP выключен. Вместо правки файла его можно включить через API: POST /api/settings/config с телом { "use_mcp": true }.

Адрес: http://127.0.0.1:<порт>/mcp, транспорт Streamable HTTP. С другой машины вместо 127.0.0.1 укажите адрес сервера.

Вместо claude mcp add подключение можно описать в файле .mcp.json проекта:

{
  "mcpServers": {
    "hamster-bot": {
      "type": "http",
      "url": "http://127.0.0.1:5000/mcp",
      "headers": { "Authorization": "Bearer <api_token>" }
    }
  }
}

Другие клиенты подключаются по тому же адресу, если поддерживают Streamable HTTP и свои заголовки запроса.

Правила доступа те же, что у API (см. Доступ). Кроме токена подходит cookie hamster-bot-token при включённом входе. Запрос без них получает 401.

Имена аргументов#

Во всех инструментах одни и те же имена: strategy — имя стратегии бота, account — имя аккаунта, folder — папка настроек тестера. Прежние имена принимаются как синонимы: name вместо strategy в get_strategy, copy_strategy, delete_strategy, name вместо account в get_account, get_account_symbols, delete_account, get_account_info, get_balance_history, compact_balance_history, path вместо folder в set_tester_settings_folder, create_tester_settings_folder, delete_tester_settings_folder. Если нет ни основного имени, ни синонима, ошибка называет ожидаемое поле. strategy в draft_strategy, draft_tester_settings и get_settings_schema — код стратегии (zigzag, mrs2), а не имя. Для настроек тестера name — имя набора настроек.

Ошибка API возвращается агенту как ошибка инструмента с кодом и текстом, например HTTP 404: {"success":false,"error":"Strategy not found"}. Очень длинные ответы обрезаются до 200 000 символов. read_tester_file отдаёт текстовые файлы целыми строками: длинный ответ заканчивается подсказкой ... [lines A-B of N; continue with offset=B]. Для длинных CSV есть параметры offset и limit (страница строк), tail_lines (последние N строк), contains (только строки с текстом) и columns (только нужные столбцы); заголовок CSV сохраняется всегда. list_tester_files принимает contains, offset и limit. HTML-отчёты большие, поэтому для сравнения прогонов лучше tester_report_summaries, а для подробностей одного прогона — read_tester_report.

Исследования в тестере#

Агент может сам вести исследование стратегии. Типичный порядок:

1. get_field_hints — узнать смысл полей настроек стратегии и конфига тестера, в том числе синтаксис parameter_mining; get_settings_schema — какие поля стратегия действительно читает: перебор недействующего поля даёт одинаковые строки.
2. create_tester_settings_folder — завести свою папку для эксперимента; copy_tester_settings_to_folder — скопировать в неё нужные настройки. Дальше передавать folder во все инструменты тестера.
3. draft_tester_settings и save_tester_settings — создать новые настройки для нужной биржи, пары и таймфрейма. Варианты существующих настроек сохранять не нужно: их задаёт overrides при запуске.
4. save_tester_config — задать период, комиссии, parameter_mining и новый name_comment для эксперимента; включить report.enable_json_report. Начало периода (StartDate) для сверки с живым ботом ставить на границу time_frame стратегии и не раньше запуска бота: стратегия работает с первой свечи своего таймфрейма, открытие которой не раньше StartDate, поэтому старт в середине 4h-свечи сдвигает первые ордера на следующую свечу. WarmupDays (по умолчанию 30) только прогревает индикаторы историей до StartDate: на этих днях стратегия не торгует и состояние не накапливает, позиция и ордера живого бота из истории не восстанавливаются. Если данных у пары меньше WarmupDays, торговля начнётся позже (предупреждение в ответе).
5. tester_download_data — загрузить свечи и дождаться окончания в tester_status. Период можно задать параметрами start и end, по умолчанию: старт конфига с прогревом .. сейчас (конфиг менять не нужно). В download.result видно, по какой день данные реально есть у каждой пары.
6. tester_run_single — проверить одну комбинацию; tester_wait (или wait_seconds при запуске) дожидается прогона и возвращает метрики, предупреждения и пути к отчётам. tester_run_batch — сравнить несколько вариантов и проверить их на нескольких периодах одним вызовом. Или tester_run_mining — перебрать все комбинации: результаты в <name_comment>/reports_history.csv (read_tester_file); queue=true ставит перебор в очередь за текущим.
7. read_tester_report — разобрать прогон: раздел summary для сравнения, итоги по парам, месяцы, сделки. Для набора стратегий — tester_portfolio_analysis: группы T/CT, корреляция, худшие дни, вклад каждой стратегии в просадку.
8. tester_report_summaries, tester_run_stress и walk_forward в конфиге — сравнить лучшие варианты и проверить их устойчивость.
9. send_tester_report_to_telegram — прислать итоговый отчёт пользователю в Telegram, если он просит.

Одна стратегия на пару#

На одном счёте на одной паре (basic.symbol) может быть только одна стратегия, и в живой торговле, и в тестере. Пар на счёте может быть сколько угодно (хоть 200), стратегии на них могут быть разными или одинаковыми, но символ среди стратегий счёта должен быть уникальным. Стратегия на занятой паре сохраняется, но не запускается (в логе DUBLICATE SUMBOL ON API); проверьте list_strategies по счёту и паре до save_strategy, copy_strategy (копируйте на другую пару) и create_strategy_from_tester. Настройки тестера, которые идут в одном прогоне, тоже должны быть на разных парах; чтобы сравнить несколько настроек на одной паре, запускайте каждую отдельно (элементы tester_run_batch или перебор с single_mode).

Реинвестирование и сравнение вариантов#

Размер позиции по basic.balance_percentage_long/_short считается от текущего баланса, поэтому прибыль реинвестируется и годовой PnL % завышается. Чтобы варианты и периоды сравнивались честно, отключите рост размера одним из способов:

1. basic.use_fix = true и basic.my_fix_balance = 50: каждый ордер считается от 50 единиц котируемой валюты (обычно USDT), независимо от баланса.
2. basic.max_balance = 2000: пока баланс меньше, бот работает с реальным балансом; при балансе 2350 размер считается от 2000, выше порога реинвестирование прекращается.
3. basic.lot_long / basic.lot_short: постоянный размер ордера, который уходит на биржу.

Некоторые стратегии могут изменить этот базовый размер по своей логике. Параметры можно задать через overrides запуска (set) или перебирать в parameter_mining.

Ответы на сохранение и запуск содержат warnings: поля, которые настройки не читают. check_tester_settings проверяет так всю папку.

Перевод в торговлю и контроль#

Проверенную настройку переносит в бота create_strategy_from_tester — стратегия создаётся на паузе, запуск — play_bot после проверки. Работу живого бота агент оценивает так: после закрытия дня, когда свечи можно скачать, прогоняет тестер на тех же настройках и за тот же период (стратегию в папку тестера копирует import_tester_settings) и получает полную статистику — в нормальном случае она совпадает с живой торговлей. Фактический результат — история баланса get_balance_history (пишется при включённом monitoring.enabled).

Инструкции сервера и описания инструментов объясняют агенту главное правило живой торговли: позиция и ордера не должны оставаться без контроля. Стратегия на паузе их не ведёт, поэтому отключение — только в порядке пауза → снять ордера → закрыть позицию → удалить (delete_strategy с full=true делает это сам).

Логи#

У каждого бота (стратегии на паре) свой лог: log_<дата>_<Биржа> <аккаунт> <пара> <таймфрейм> <стратегия> <имя>.log — уровни, сигналы, выставленные и снятые ордера, исполнения, изменения позиции и ошибки стратегии; по нему видно, почему бот торговал или не торговал. У каждого аккаунта — log_<аккаунт>_<дата>.log: балансы и позиции с биржи, ответы и ошибки API биржи, лимитер позиций, close_by_margin. Общий лог программы — log_<дата>.log (get_log), логи тестера — TESTER_*.log. Формат даты в именах разный, поэтому файл ищут по имени стратегии или аккаунта: list_log_files с contains, затем read_log_file.

Примеры использования#

Ниже — запросы к агенту и вызовы инструментов, которые он делает. Аргументы показаны в JSON, как их передаёт MCP-клиент. Папка lut_now, имена настроек и даты — для примера.

tester_run_single {
  "settings": ["*"], "folder": "lut_now", "wait_seconds": 240,
  "overrides": [
    { "match": "T_*", "mul": { "basic.balance_percentage_long": 2, "basic.balance_percentage_short": 2 }, "cap_pct": 10 },
    { "match": "C_MU", "set": { "basic.use_short": false } }
  ],
  "periods": [["2026-05-01", "2026-08-01"], ["2026-08-01", "2026-10-26"]]
}

tester_run_batch {
  "folder": "lut_now", "parallel": 2, "wait_seconds": 240,
  "periods": [["2026-05-01", "2026-08-01"], ["2026-08-01", "2026-10-26"]],
  "runs": [
    { "name": "base", "settings": ["*"] },
    { "name": "T x2", "settings": ["*"], "overrides": [{ "match": "T_*", "mul": { "basic.balance_percentage_long": 2 } }] },
    { "name": "без L_X", "settings": ["*"], "overrides": [{ "match": "L_X", "exclude": true }] },
    { "name": "только лонг", "settings": ["*"], "sides": "long" }
  ]
}

Примеры: что можно попросить у агента

Агенту пишут обычным языком: он сам выбирает инструменты, вызывает их по очереди и объясняет результат.

Исследования в тестере

Рабочий бот: чтение и анализ

Управление: с подтверждением

Перед реальными действиями агент показывает, что собирается сделать, а клиент запрашивает подтверждение на каждый опасный инструмент, если разрешения не выданы заранее (см. Границы доступа).