DeepThonk MCP server

DeepThonk

thonk harder, not richer.

DeepThonk implements the OpenDeepThink algorithm (Zhou et al., 2026, arXiv:2605.15177) as a budget-friendly, provider-neutral "deep think / pro mode" wrapper, with first-class DeepSeek support. See Acknowledgments.

DeepThonk runs a population of candidate answers through pairwise judging, Bradley-Terry ranking, critique-guided mutation, elite preservation, and a final dense ranking pass. The CLI and MCP server both call the same TypeScript core engine.

Designed for agents. Every algorithm dimension — population shape (n, k, t, m), regularization (lambda), per-phase temperatures, prompt style, and per-phase prompt templates — is reachable inline through MCP arguments and CLI flags. CLI can load prompt files with --prompts or inline JSON with --prompts-json; MCP accepts inline structured prompt args. Every intermediate artifact (config, candidates, populations, comparisons, scores, per-call usage, status) is exposed as an MCP resource so an agent can inspect any step. See Customization for the full agent-composable surface.

Use it for hard, verifiable reasoning, coding, planning, and synthesis where breadth plus judgment can beat one expensive single shot. Avoid it for highly subjective tasks where judge noise dominates.

Quickstart

Requires Node ≥ 22.13.

Run without installing:

npx -y deepthonk plan --profile paper
npx -y deepthonk run --provider fake --profile quick \
  --task "Find the smallest positive integer divisible by 3, 4, and 5." \
  --out runs/test-quick
npx -y deepthonk inspect runs/test-quick

Or install globally:

npm install -g deepthonk
deepthonk plan --profile paper

The paper profile plans 285 model calls and 8 sequential rounds. Confirm budget and provider pricing before pointing it at paid models. The short alias dt is installed alongside deepthonk. Develop from source: see Development.

DeepThonk is an independent TypeScript reimplementation and practical integration layer; the published algorithm is the load-bearing part. Cost guarantees rely on provider pricing being present in config. Trace-v2 resume can reuse validated per-item receipts after a crash, while older traces replay an incomplete phase wholesale. The MCP HTTP transport remains loopback-only. The included acceptance smoke uses the deterministic fake provider and a toy task — it is not a CF-73 / HLE reproduction; see docs/ and Acknowledgments for the canonical paper and Python reference.

Setup

Create a reusable local config:

deepthonk setup \
  --provider deepseek \
  --api-key-env DEEPSEEK_API_KEY \
  --fast-model deepseek-v4-flash \
  --judge-model deepseek-v4-pro

By default this writes ~/.config/deepthonk/config.yaml. deepthonk run loads that file automatically when --config is not supplied. If you pass --api-key, setup stores it in ~/.config/deepthonk/env; otherwise it uses the named environment variable from your shell.

DeepSeek

export DEEPSEEK_API_KEY=...
deepthonk run \
  --task task.md \
  --profile paper \
  --provider deepseek \
  --generator-model deepseek-v4-flash \
  --mutator-model deepseek-v4-flash \
  --judge-model deepseek-v4-pro \
  --out runs/task-paper

DeepSeek is implemented as an OpenAI-compatible profile using https://api.deepseek.com/v1. DeepThonk ships default USD pricing for deepseek-v4-flash and deepseek-v4-pro from the official DeepSeek pricing page, including cache-hit/cache-miss input rates. Model names and prices are still editable config because both can change.

Before paid runs, inspect cost shape and resolved config:

deepthonk plan --config ~/.config/deepthonk/config.yaml
deepthonk run --task task.md --config ~/.config/deepthonk/config.yaml --profile quick --dry-run

Shortened. The full README is on GitHub.