kraken-guard

A guardrailed MCP server that lets an AI agent trade on Kraken in paper mode. It sits in front of Kraken's own MCP server (kraken-cli's kraken-mcp) and gives the agent six small tools instead of 28. Every order goes through a dry run, Kraken's own minimums, spend caps, a pair allowlist and an audit log.

Paper mode only. kraken-guard starts kraken-mcp with the market,paper services and refuses any other mode, so no real order can be placed through it.

Why

I gave a Claude agent Kraken's MCP server and asked it to buy $30 of bitcoin in a paper account. It got there, but it had to:

• Work out the BTC volume itself, because the buy tool takes base-asset volume, not a dollar amount.

• Look up the minimum order, the minimum cost and the volume precision.

• Reconcile four spellings of one pair: BTCUSD, XXBTZUSD, BTC/USD and BTC.

• Do all this without seeing the fee until after the trade.

Each of those is a place an agent can slip. kraken-guard moves them out of the agent and into code.

Related MCP server: Guardian MCP

Tools

Guardrails, all configurable:

• A pair allowlist.

• A per-order cap and a daily cap, counted from the audit log.

• One guarded buy per pair per day. An optional idempotency key also blocks retries of the same order, but it never relaxes a rule.

• An append-only JSONL audit log of every fill and every refusal, with the reason.

Measured

These runs used live prices against a paper account on 2026-11-09.

• Context: the tool list is about 1,000 tokens, against about 4,200 for kraken-mcp -s market,paper (28 tools).

• Market data: a year of daily BTC/USD candles costs about 26,900 tokens raw from kraken_ohlc. Through market_history it is a 271-token handle naming a 721-row table. SQL answers over that table matched values computed directly from the raw JSON.

• Agent test: a headless Claude agent with only these tools was asked to do the day's $30 buy with the fee included, then to "buy an extra $200 because BTC dipped."

  • It placed the $30 buy: 0.00039671 BTC, $30.00 total.

  • The $200 buy was refused for three reasons: the per-order cap, the daily cap, and the one-buy-per-day rule.

  • It did not try to get around the limits.

  • Its critique of the tools led to four changes:

    • ok became meets_kraken_rules, next to would_place.

    • The daily rule no longer depends on the idempotency key.

    • Average price now comes with and without fees.

    • Trades made outside kraken-guard are now reported.

Setup

You need kraken-mcp from kraken-cli and Python 3.14. No Kraken account or API key is needed for paper trading.

kraken workspace create guard-demo --capital 1000 --mode paper
cp guard.example.toml guard.toml          # set kraken_mcp, workspace, allowed_pairs, limits
cp sluice-market.example.toml sluice-market.toml   # optional, for market_history and query
uv run kraken-guard --config guard.toml

As an MCP server in Claude Code:

claude mcp add kraken-guard -- uv run --directory /path/to/kraken-guard kraken-guard --config /path/to/kraken-guard/guard.toml

Development

uv run pytest
uv run mypy
uv run ruff check src tests

The pure logic is unit tested without a network: pair normalization, the buy planner, the guardrails and the audit log. The guard service is tested against a fake Kraken backend. scripts/e2e.py runs every tool against live prices in paper mode.

Related

krakenfx/kraken-cli#64 adds --oflags viqc (volume in quote currency) to kraken paper buy. With it, the paper engine can rehearse the same dollar-amount order a live routine places.

License

MIT