hamster-bot new: MCP

RU EN PT

Who does what#

The path of one command: “close the BTC position”#

1. 1The person writes a message in the Claude app. It goes to the Anthropic cloud over HTTPS.
2. 2Claude Code on the VPS polls the cloud itself and picks up the message. The model decides which tool to call.
3. 3The agent calls close_position on /mcp with the api_token. The bot checks the token.
4. 4The MCP server turns the call into an ordinary request to /api/* of the same bot and passes the same token. That is why MCP and the API share the same logic and checks.
5. 5The API passes the command to the bot core. The core takes the key of this account.
6. 6The connector signs the request and sends it to the exchange. The result returns along the same chain and appears on the phone.

What happens if one of the parts goes down#

What the agent can do through MCP#

Of the 87 tools, 42 only read data (readOnlyHint), and 25 are marked as dangerous (destructiveHint): they trade, start bots or irreversibly change data. These are market orders, closing positions, cancelling orders, starting bots, saving and deleting strategies and keys, changing the config, shutting down and updating the program. The tester works on historical data and does not trade on the exchange.

Access limits#

• The token gives owner rights. With the api_token, all 87 tools are available, including trading, deleting accounts and shutting down the program. There is no read-only mode.
• Confirmation depends on the client. Dangerous tools are only marked; it is up to the MCP client to ask the person. In autonomous mode permissions are granted in advance, and the agent acts without asking.
• CLAUDE.md sets rules but does not protect. The agent follows risk limits and the ban on leaving its folder as instructions. If it has a shell under the same user as the bot, it can technically read the bot's files.
• The token is not always needed. When Telegram login is off, requests to /mcp from the same machine pass without a token. This applies to any local process.
• The web interface, API and MCP share one port. For an agent on the same VPS, the 127.0.0.1 address is enough. From another machine the token travels in plain text, so over the internet you need an HTTPS proxy or an SSH tunnel.

How to run it on a VPS#

1. In the bot's settings_program.json, no restart needed:

   Copy

   "use_mcp": true

2. A session that survives closing SSH:

   Copy

   tmux new -s agent

3. Connect the agent to the bot:

   Copy

   claude mcp add --transport http hamster-bot http://127.0.0.1:<port>/mcp --header "Authorization: Bearer <api_token>"

4. Open the session for the phone:

   Copy

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

5. In the session chat: autonomous work on a schedule:

   Copy

   /loop 6h Continue working per CLAUDE.md

Connection details#

MCP is off by default. Instead of editing the file, you can enable it via the API: POST /api/settings/config with the body { "use_mcp": true }.

Address: http://127.0.0.1:<port>/mcp, Streamable HTTP transport. From another machine, use the server address instead of 127.0.0.1.

Instead of claude mcp add, the connection can be described in the project's .mcp.json file:

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

Other clients connect to the same address if they support Streamable HTTP and custom request headers.

The access rules are the same as for the API (see Access). Besides the token, the hamster-bot-token cookie works with login enabled. A request with neither gets 401.

Argument names#

All tools use the same names: strategy — bot strategy name, account — account name, folder — tester settings folder. The old names are accepted as synonyms: name instead of strategy in get_strategy, copy_strategy, delete_strategy, name instead of account in get_account, get_account_symbols, delete_account, get_account_info, get_balance_history, compact_balance_history, path instead of folder in set_tester_settings_folder, create_tester_settings_folder, delete_tester_settings_folder. If neither the main name nor a synonym is present, the error names the expected field. strategy in draft_strategy, draft_tester_settings and get_settings_schema is a strategy code (zigzag, mrs2), not a name. For tester settings name is the settings set name.

An API error is returned to the agent as a tool error with the code and text, for example HTTP 404: {"success":false,"error":"Strategy not found"}. Very long responses are cut at 200,000 characters. read_tester_file returns text files in whole lines: a long response ends with the hint ... [lines A-B of N; continue with offset=B]. For long CSV files there are the parameters offset and limit (a page of lines), tail_lines (last N lines), contains (only lines with the text) and columns (only the needed columns); the CSV header is always kept. list_tester_files accepts contains, offset and limit. HTML reports are large, so to compare runs use tester_report_summaries, and for details of one run read_tester_report.

Research in the tester#

The agent can research a strategy on its own. A typical order:

1. get_field_hints — learn the meaning of strategy settings and tester config fields, including the parameter_mining syntax; get_settings_schema — which fields the strategy actually reads: mining an ineffective field gives identical rows.
2. create_tester_settings_folder — create your own folder for the experiment; copy_tester_settings_to_folder — copy the needed settings to it. Then pass folder to all tester tools.
3. draft_tester_settings and save_tester_settings — create new settings for the needed exchange, pair and timeframe. Variants of existing settings need not be saved: overrides sets them at run time.
4. save_tester_config — set the period, fees, parameter_mining and a new name_comment for the experiment; enable report.enable_json_report. To compare with a live bot, place the period start (StartDate) on a boundary of the strategy's time_frame and not earlier than the bot's start: the strategy works from the first candle of its timeframe that opens at or after StartDate, so a start in the middle of a 4h candle moves the first orders to the next candle. WarmupDays (default 30) only warms up indicators with history before StartDate: on these days the strategy does not trade or accumulate state, and the live bot's position and orders are not restored from history. If a pair has less data than WarmupDays, trading starts later (a warning in the response).
5. tester_download_data — download candles and wait for completion in tester_status. The period can be set with start and end, by default: the config's start with warmup .. now (no need to change the config). download.result shows up to which day each pair actually has data.
6. tester_run_single — check one combination; tester_wait (or wait_seconds at start) waits for the run and returns metrics, warnings and report paths. tester_run_batch — compare several variants and check them on several periods with one call. Or tester_run_mining — go through all combinations: results in <name_comment>/reports_history.csv (read_tester_file); queue=true queues the mining after the current one.
7. read_tester_report — analyze a run: the summary section for comparison, results by pair, months, trades. For a set of strategies — tester_portfolio_analysis: T/CT groups, correlation, worst days, each strategy's contribution to drawdown.
8. tester_report_summaries, tester_run_stress and walk_forward in the config — compare the best variants and check their robustness.
9. send_tester_report_to_telegram — send the final report to the user in Telegram if asked.

One strategy per pair#

On one account, one pair (basic.symbol) can have only one strategy, both in live trading and in the tester. An account can have any number of pairs (even 200), and strategies on them can be different or identical, but the symbol must be unique among the account's strategies. A strategy on an occupied pair is saved but does not start (the log shows DUBLICATE SUMBOL ON API); check list_strategies by account and pair before save_strategy, copy_strategy (copy to a different pair) and create_strategy_from_tester. Tester settings running in one run must also be on different pairs; to compare several settings on one pair, run each separately (tester_run_batch items or mining with single_mode).

Reinvestment and comparing variants#

Position size from basic.balance_percentage_long/_short is calculated from the current balance, so profit is reinvested and the annual PnL % is inflated. To compare variants and periods fairly, disable size growth in one of these ways:

1. basic.use_fix = true and basic.my_fix_balance = 50: each order is calculated from 50 units of the quote currency (usually USDT), regardless of the balance.
2. basic.max_balance = 2000: while the balance is lower, the bot works with the real balance; at a balance of 2350 the size is calculated from 2000, above the threshold reinvestment stops.
3. basic.lot_long / basic.lot_short: a constant order size that goes to the exchange.

Some strategies may change this base size by their own logic. The parameters can be set through the run's overrides (set) or mined in parameter_mining.

Save and run responses contain warnings: fields the settings do not read. check_tester_settings checks a whole folder this way.

Moving to trading and monitoring#

create_strategy_from_tester moves verified settings to the bot — the strategy is created paused, and play_bot starts it after checking. The agent evaluates a live bot like this: after the day closes and its candles can be downloaded, it runs the tester on the same settings and period (import_tester_settings copies the strategy to the tester folder) and gets full statistics — normally they match live trading. The actual result is the balance history get_balance_history (written with monitoring.enabled on).

The server instructions and tool descriptions explain the main rule of live trading to the agent: a position and orders must not be left without control. A paused strategy does not manage them, so switching off is only in the order pause → cancel orders → close the position → delete (delete_strategy with full=true does this itself).

Logs#

Each bot (strategy on a pair) has its own log: log_<date>_<Exchange> <account> <pair> <timeframe> <strategy> <name>.log — levels, signals, placed and cancelled orders, fills, position changes and strategy errors; it shows why the bot did or did not trade. Each account has log_<account>_<date>.log: balances and positions from the exchange, exchange API responses and errors, position limiter, close_by_margin. The general program log is log_<date>.log (get_log), tester logs are TESTER_*.log. The date format in the names varies, so files are found by strategy or account name: list_log_files with contains, then read_log_file.

Usage examples#

Below are requests to the agent and the tool calls it makes. Arguments are shown in JSON, as the MCP client sends them. The lut_now folder, settings names and dates are examples.

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": "without L_X", "settings": ["*"], "overrides": [{ "match": "L_X", "exclude": true }] },
    { "name": "long only", "settings": ["*"], "sides": "long" }
  ]
}

Examples: what you can ask the agent

Talk to the agent in plain language: it picks the tools, calls them one after another and explains the result.

Research in the tester

Running bot: reading and analysis

Control: with confirmation

Before real actions the agent shows what it is about to do, and the client asks for confirmation for every destructive tool, unless permissions were granted in advance (see Access limits).