nuthatch
Turn an EVM contract's history into a local SQL database. One Rust binary, no Postgres, no subgraph to write, and an MCP server built in.
· Website: www.nuthatch-indexer.com
Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
docker run -i --rm ghcr.io/nightswatchhq/nuthatch:4.0.0Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
claude mcp add io.github.nightswatchhq-nuthatch -- docker run -i --rm ghcr.io/nightswatchhq/nuthatch:4.0.0รันในเทอร์มินัล
{ "mcpServers": { "io.github.nightswatchhq-nuthatch": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/nightswatchhq/nuthatch:4.0.0" ] } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
Turn an EVM contract's history into a local SQL database. One Rust binary, no Postgres, no subgraph to write, and an MCP server built in.
· Website: www.nuthatch-indexer.com
Query an EVM contract's indexed history with SQL, via a local nuthatch nest and nuthatch dev.
curl -fsSL https://nuthatch-indexer.com/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
nuthatch init 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 --alias weth
nuthatch dev --backfill 300
Then, in a second terminal:
nuthatch sql "SELECT count(*) FROM weth__transfer"
The installer covers macOS Apple Silicon and Linux x86_64 and aarch64, and the export adds its
directory, which a fresh macOS shell lacks. init indexes WETH and detects its chain. The block
carries no # comments because zsh, the macOS default, does not treat a pasted # as one: it
passes the rest of the line on as arguments.
The Linux binary needs glibc 2.35 or newer to run from 4.1.0, which is also what it is built on;
4.0.x ran on 2.34. No Intel Mac binary is published: there, and on other platforms, build from
source with Rust 1.95.0 (docs/install.md).
init creates a nest: a directory holding the contract's ABI, its config and, once dev runs,
its indexed data. --backfill 300 starts 300 blocks behind the tip, about an hour of mainnet, so there
are rows to query within seconds on the bundled public endpoints. Without it, dev backfills from the
contract's deployment block: for WETH that is 21 million blocks, a long backfill on free public endpoints
and a job for your own RPC (--rpc).
Those five lines, run as written on the 4.10.1 release on 2026-10-05, took 13 s from the curl to a
non-zero count in a clean macOS shell on an M5 Pro, and 21 s in a fresh ubuntu:24.04 container
(docs/readme-check-2026-10-05.md, which records every command in
this file).
Like Ponder, nuthatch reads the chain over JSON-RPC, so it needs an endpoint, and a provider may charge for one. The public endpoints it bundles are for trying it out, not for keeping it running. It complements The Graph rather than replacing it: a subgraph serves an application from a network of indexers, while a nest puts a contract's history in a database on your own machine.
Why. Getting at a contract's history usually means writing a subgraph or handler code, running a database, or renting someone else's copy. nuthatch generates the tables from the ABI, runs as one process with nothing else to install, and keeps the data on your machine: at most 2 GB of RAM per chain, no telemetry unless you opt in, no account. The built-in MCP server lets Claude or any MCP client query it.
init 0xAddr resolves the ABI (Sourcify, then Etherscan), generates the schema and
decoders, and scaffolds the project. You write nothing.init (nuthatch count),
and its totals are public. Most people say no or are never asked, so
they are floors.An earlier example, now finished: Arcaidia, a speed layer over Circle's CCTP built at ETHOnline 2026, read its indexed state from two nests on Ethereum Sepolia and Arc Testnet: its solver discovered intents there, its settlement agent tracked CCTP there, and its web console rendered from them. The nests were stopped on 2026-09-29.
More at nuthatch-indexer.com/stories.
There is no hosted platform. We will run a nest for you on the stock binary, with no billing and no accounts: ask on the Discord.
curl -fsSL https://nuthatch-indexer.com/install.sh | sh
That downloads the prebuilt binary for your platform from the latest release, verifies its SHA-256,
and installs it to ~/.local/bin (override with NUTHATCH_INSTALL_DIR). No compiler is
involved. A stock macOS shell does not have ~/.local/bin on its PATH, which is why the quickstart
above exports it; add the same line to ~/.zshrc (or ~/.bashrc) to keep it for new terminals. Prebuilt binaries cover macOS Apple Silicon and Linux x86_64 and aarch64 (aarch64 from the release after 4.11.0) and are attached to every
release with their checksums, if you would rather fetch one by hand. No Intel Mac binary is
published; the installer says so and points at the source build below.
The Linux binary is dynamically linked and needs one thing, measured off the published
artifact with objdump -T rather than inferred:
GLIBC_2.34, so 2.34 was what you needed to run
it and 2.35 only what we compiled it on (#978);
4.1.0 references hypot at GLIBC_2.35, where libm re-versioned it, so the two numbers now agree.It links libc, libm and libgcc and no C++ runtime. Releases before 4.1 embedded DuckDB and
also needed libstdc++ from GCC 11.
Debian 12 and Ubuntu 22.04 clear it. RHEL 9 and Amazon Linux 2023 ship glibc 2.34 and ran 4.0.x; from 4.1.0 they need the source build.
Verify who built it. Every release binary carries a build provenance attestation, which a checksum cannot give you:
gh attestation verify nuthatch-x86_64-unknown-linux-gnu.tar.gz --repo nuthatch-org/nuthatch
From source, which is the only route on a platform we do not publish a binary for, Intel Macs included (the Intel build has not been verified on Intel hardware):
rustup toolchain install 1.95.0
cargo +1.95.0 install --git https://github.com/nuthatch-org/nuthatch nuthatch
The +1.95.0 is required: cargo install --git ignores the repo's toolchain pin, and a newer
default toolchain fails to compile a dependency.
Container images are published per release to ghcr.io/nuthatch-org/nuthatch - :<version> for
embedded, :<version>-scaled for the scaled build. The image ships the same binary attached to the
release, so the two cannot drift.
docs/install.md has the detail behind each of these: how the ABI floor is measured,
what the attestation proves and what --repo is for, and why the toolchain pin exists.
Chains. Ethereum, Arbitrum One, Base, BSC, Polygon, Gnosis, Optimism, Monad and Robinhood Chain are built in, with
measured public endpoints and tuned finality settings - omit --chain and nuthatch probes each for
your contract's bytecode and picks the one it lives on. Point at your own node with --rpc.
Any other EVM chain works too - World Chain, Base Sepolia, your own devnet. Name the chain and say where it lives:
nuthatch init 0xADDR --chain world-chain --rpc https://your-endpoint.example
The chain id is read from the endpoint itself, so there is nothing to look up or type wrong. On
one of the nine built-in names --rpc is not consulted for the chain id, but it is the pool: your
endpoints replace the bundled public ones outright. Omit --rpc on an unregistered name and the
refusal tells you the remedy.
See running an unlisted EVM chain for the
finality caveat, which is the part worth reading: a chain whose finalized tag runs close to the tip
needs a depth-based policy instead, or you seal immutable Parquet that could never be corrected.
nuthatch assumes a paid RPC endpoint, or your own node, for anything you intend to keep running. That is the golden path.
Worth knowing, since we are being precise about it: most figures currently in
docs/benchmarks.md were measured against public endpoints, and that is a
known weakness of those numbers rather than a recommendation - a benchmark taken through a
rate-limited endpoint measures the endpoint. On one workload the network was 99.3% of backfill wall
clock (the same tape live against a public endpoint and replayed from disk, 2026-08-23, in
docs/benchmarks.md), which is why the replay rig (RFC-0039) exists and why those figures carry that
caveat on the page itself.
The free public endpoints bundled per chain exist for one job: so init → dev works with zero
setup. Treat them as testing and initial validation. Why they are not fine for real work, said here
rather than discovered at 3am:
/ready reports
stalled when that happens.Check an endpoint before you trust a backfill to it. nuthatch doctor probes one and reports the
largest getLogs window it will actually serve, its batch limit, and whether it has archive history -
measured, not taken from the provider's documentation:
nuthatch doctor --rpc https://your-endpoint.example --address 0xADDR
Use your own endpoint for anything you care about - your own node, or a paid provider:
nuthatch init 0xADDR --chain arbitrum-one --rpc https://your-endpoint.example/arbitrum
nuthatch dev --rpc https://your-endpoint.example/arbitrum # or set rpc_urls in nuthatch.toml
--rpc is repeatable, and nuthatch round-robins across the pool with per-endpoint health tracking, so
listing two or three endpoints gets you failover as well as throughput. Every endpoint in a pool must be
on the same chain - nuthatch verifies this at startup and refuses to run against a mixed pool, since
indexing against the wrong chain corrupts state silently.
Every declared event becomes a table named {alias}__{event} (e.g. usdc__transfer), carrying the
event's fields plus block_number, block_hash, block_timestamp, tx_hash, log_index,
address and a _seq ordinal.
Since 3.11
block_timestampis taken from the log, where current execution clients putblockTimestamp. A node that leaves it out costs a block-header round trip per block: on OBIB case 1, before 3.11, that took the backfill from 74.8 s to 1,689 s, 22.6x (RFC-0029 §4c, 2026-07-31). A nest that will never ask a time-series question can drop the column withinit --no-timestamps. It is an init-time choice: changing it later is a breaking schema change and a full re-index, so it is worth a moment's thought and is deliberately not a flag you can flip. Details.
# one-shot from the terminal (prints an aligned table; --json to pipe to jq)
nuthatch sql 'SELECT src AS sender, count(*) AS n FROM weth__transfer GROUP BY 1 ORDER BY n DESC LIMIT 5'
# or over HTTP, against a running `nuthatch dev`
curl 'localhost:8288/sql?q=SELECT%20count(*)%20FROM%20weth__transfer'
nuthatch sql queries the local store when dev is stopped, and transparently falls back to the
running instance's API when dev holds it - the same command works either way./sql returns degraded
and degraded_tables naming the affected tables, nuthatch sql prints a warning line, and the MCP
server carries the same notice. The caveat is a fact about the nest, not about the row count you
happened to get, so it appears whether or not this particular query touched the gap.bool
column, stored as exact text 'true'/'false', explains why it blows up inside COALESCE, CASE
and bool_and. Same treatment on /sql, the MCP sql tool and nuthatch sql.uint256 values are exact text; amounts that fit in 38 digits also get a
{col}_dec DECIMAL view. SUM(value_dec) is those values: a full-width word is NULL and is not a
term. WHERE NOT {col}_overflow writes the same sum out. Ids, nonces and hashes stay on the raw
column.nuthatch diff --from X --to Y (or --block,
--tx, --since-last) tells a range in fixed sentences with exact amounts: every ownership,
pause, upgrade and role change, the largest movements per token, new holders, approvals with
unlimited ones named, and every other table counted. --flow draws the token flow as text, JSON,
DOT or Mermaid. The same document comes from GET /diff and the MCP diff tool, and every output
ends with what the nest cannot see (RFC-0071).nuthatch mcp) - point Claude (or any
MCP client) at your indexer and ask your contract's data in plain English, fully offline.We ran someone else's benchmark rather than writing our own: Sentio's OBIB.
Case 1 indexes Transfer from LBTC across 22.2M Ethereum blocks.
Case 2 is case 1's contract with per-account balances, and OBIB's implementations get them with one
balanceOf() per account. We make none. For a plain ERC-20 the balance is the transfer history,
so we index the token's whole life instead and derive it - trading 2.5M extra blocks of cheap getLogs
for zero eth_call round trips.
Reference times for the same case, from OBIB's README: Sentio 7.78 min, Envio 8.54 min, Subsquid 46.85 min.
Two caveats, stated rather than buried. First, this is deliberately not like-for-like on range:
OBIB windows to 100,001 blocks, we index 2,611,334. On OBIB's own range we take 9.3 s - but that
run cannot produce the case's output at all, because absolute balances need history from before the
window, which is precisely why the benchmark makes the RPC calls. Second, "derived" is proven rather
than asserted: at the pinned end block, 39 sampled accounts - the ten largest, ten smallest non-zero,
ten zero-balance and ten by address order - all matched balanceOf(), including every zero-balance
account, which is the case an off-by-one in the ledger would betray. The count is 7,634 and not 7,635
because 0x0 is the mint/burn counterparty rather than a holder.
Case 6 is the factory-template case: the Uniswap V2 factory over blocks 19,000,000-19,010,000,
discovering pairs from PairCreated and indexing Swap on every child it finds. No per-child config,
no redeploy, one rule.
The figure this table used to show, 49.5 s with 16 requests and 247 MB, is withdrawn: 1.0.1 on
a closed Alchemy account. Nobody, us included, can rerun it. Its report stays in the tree as
docs/bench/obib-case6.json for the record, not as a claim.
For scale, OBIB's own published figures for case 6 differ between its two tables: its results table gives Envio HyperIndex 1.92 min, Subsquid 5.34 min and Sentio 14.36 min, while its case-6 page reports Envio at 30 s from an earlier round. We quote both, and neither is a like-for-like ranking: those runs were on other machines, other days and other endpoints, and Envio and Subsquid serve this from their own pre-indexed networks, where nuthatch runs against plain JSON-RPC.
Cases 1 and 2 were measured in July and August 2026 against the same Alchemy account case 6's old
figure is withdrawn for, so nobody can rerun those two as they were; they stay because their
artifacts carry commit, provider and hardware, and case 2 has been rerun on the current release
without an account, in the row above. The artifacts are
docs/bench/obib-case1.json,
docs/bench/obib-case2.json,
docs/bench/obib-case2-4.10.1-tenderly-2026-10-05.json and
docs/bench/obib-case6-4.7.0-tenderly-2026-10-05.json;
nuthatch bench backfill re-runs any of them.
The case-2 nest is committed at obib-case2/ - keyless, so the endpoint arrives via
--rpc, and verified to rebuild from a clean checkout.
The case-6 nest is published at nuthatch-org/obib-case6
so the run can be reproduced rather than believed, and is submitted upstream as
sentioxyz/open-blockchain-indexer-benchmark#3.
Case 6 needs no account at all: the release binary, that nest and the public gateway are the whole
setup.
Wall clock on a shared endpoint is the provider's number as much as ours. On the withdrawn Alchemy
setup we checked whether provider caching flattered the case-6 figure by re-running an adjacent,
never-fetched range of the same size: 48.2 s against 49.5 s
(obib-case6-cold-control.json, 2026-08-04), so caching
was not the explanation. The event count was the same in every run, and so was the request count for
a given version: 16 then, 14 on 4.7.0 in all five runs. Those are the honest measure of range
control.
Two things the case 1 number is worth knowing about:
block_timestamp - one serial round trip per block,
for a column that workload never stores: 1,689 s with timestamps against 74.8 s without, on the
same range and endpoint (RFC-0029 §4c, 2026-07-31).
Timestamps are now demand-driven and the log window adapts to what an endpoint will actually serve.Case 6 found a defect too, in the harness rather than the indexer: bench backfill fetched a fixed
address list, so a factory nest was measured without its children - 232 events in 2.6 s against an
expected 35,039, reported as a success (#310).
Running an outside benchmark has now found two things our own testing did not.
Analytical queries run on Burrmill, our engine on
DataFusion, over sealed Parquet. Until 4.1 they ran on DuckDB, and the change was not made for speed:
on our largest nest, through /sql, Burrmill took about 2.5 times DuckDB's time per statement
with eight times the memory allowed to each session, measured 2026-10-01 for the
4.1.0 release notes. What it buys is one language in the binary and exact
arithmetic that refuses rather than wraps. The reasons and the log of the switch are in
Replacing DuckDB, after all.
RPC ingestion → deterministic decode → redb hot store (the unsealed tip)
│
past finality → content-addressed Parquet segments
│
Burrmill reads segments read-only → SQL (hot ∪ sealed)
eth_getLogs, decodes each window into the hot
store, and seals a segment once its blocks are past the chain's finality (a depth of 64 on mainnet;
a tag or a depth per chain). Reorgs only ever touch the hot store; a sealed segment is never
rewritten./sql attaches read-only.
Analytical SQL has run on Burrmill, our engine on
DataFusion, since 4.1.0; DuckDB was the engine before that and is no longer in the binary.entities.toml are maintained by DBSP as blocks arrive; a reorg is a retraction. On Arbitrum,
[extract] l1_blocks = true adds a table of each block's L1 block number (4.6.0).publish mirrors a nest's sealed segments to a bucket and seed starts a nest
from one instead of backfilling (4.9.0); a public mirror of four Graph Protocol nests is at
nuthatch-indexer.com/mirror.nuthatch has a Model Context Protocol server compiled in, so a coding agent can query your contract's data in plain English - offline, no phone-home. Wiring it is one step:
nuthatch dev & # the index the agent will query
nuthatch mcp --print-config # prints a copy-paste config for Claude Code / any MCP client
Or add it to Claude Code directly:
claude mcp add nuthatch -- nuthatch mcp --url http://127.0.0.1:8288
A nest behind a gateway that wants a bearer token: --token-env NEST_TOKEN names the variable that
holds it (NUTHATCH_MCP_TOKEN is read by default), so the token never goes on the command line.
Then just ask: "what are the top USDC holders?" - the agent writes the SQL and runs it against your nest. (Making that correct on the first try is the semantic-layer work.)
Teach your agent to build nests too. Install the builder skill and an agent can drive nuthatch
itself - init, config, factories, compliance, multi-nest runtimes, troubleshooting - before you even have a nest:
cp -r skills/nuthatch-builder ~/.claude/skills/ # or your repo's .claude/skills/
Its CLI/config references are generated from the binary and CI-checked for drift, so the skill never lies about a flag (RFC-0017).
The core is "your contract → SQL." Beyond that, nuthatch has a full feature set for teams and operators who need more - none of it in the way of the happy path:
nuthatch.toml; index them together.[[calls]] block reads a contract at a fixed block and
stores the result as a table, optionally with calldata built from the row that triggered it - the
contract.balanceOf(event.params.user) a subgraph would write. Pinning the block is what keeps it
deterministic: the answer is fixed, so two operators re-running the same nest get the same bytes,
and the result is content-addressed on (chain_id, block, contract, calldata). Needs --state-rpc
pointed at an archive node.[[ipfs]] block turns a column of content addresses
into a table of resolved documents. Every body is re-hashed and checked against the CID it claims
to be, so a gateway serving the wrong bytes yields no row rather than a plausible one. The CID is
taken from whatever shape the contract stored - a bare CID, an ipfs:// URI, a gateway URL, or a
raw 32-byte digest - and the host is discarded, because that string came from a log and
honouring it would let whoever emitted the event choose what your indexer connects to.{template}__* tables - no redeploy per child.views/*.sql are named SQL evaluated at query time over hot ∪ sealed,
not IVM. And a nest can declare its own authored incremental entities in entities.toml
(RFC-0041): a SELECT that DBSP maintains as
blocks arrive, served from /derived and queryable by name from /sql, with reorgs handled as
retractions like the built-ins. On a copy of the Lodestar nest that took the indexer_rewards panel
from a p50 of 2.15 s to 87.7 ms (docs/bench/3.0.0-alpha-live.md)./_admin/ - status, tables, view/nest inspector.
Localhost-open; off-localhost it requires a token per request.[address_history] table and no contracts
watches accounts rather than contracts and serves their history Etherscan-shaped at /api, for
rotki and anything else that speaks that interface. It runs locally on its own path, keeps its rows
in the nest's own store rather than SQL tables, and your RPC sees which addresses you watch.
Config reference.init's own
code compiled to wasm, and opens postcards: links that pin a published nest's segments by hash, so a
host can withhold an answer but not change one. This is decode and Burrmill in wasm, not the removed
WASM handler layer.getLogs per window, and a
runtime can span multiple chains with one isolated cursor per
chain - a Base nest and an Arbitrum nest in one runtime. Per-nest isolation, and a footprint budget
per active-chain cursor (≤2 GB). A capability, not a mandate: one chain per runtime stays the simple
default.POST /_admin/nests mounts one and
DELETE /_admin/nests/<name> unmounts one, live, so a change to the nest set no longer stops every
co-tenant. A mount is admitted only if it fits the cursor's RAM budget (refused, never warned),
catches up before it joins so it never drags co-tenants back through history, and only then gets
routes; an unmount is a drain, not a route removal. The set persists in mounts.toml, so a restart
converges on what you last asked for. Suspend, resume, move a name to a new NID without a gap,
dry-run a mount for its projected footprint, and fetch a NID from a registry at mount time: all in
nest lifecycle operations.nuthatch worker) whose members take cursor leases, and a query-FE tier (nuthatch serve)
that serves from shared state and owns nothing. A role flag, never a fork, and opt-in at build time
(--features postgres-store), so the published binary carries no database driver. Ownership is
enforced by the store: every write carries a fence, and a stalled worker that wakes up finds its
writes refused. Workers pull the nests they are assigned from a registry by content address, so
re-tagging a version cannot change what a fleet runs. This is the self-hosted distributed path
for one operator's cooperating nests; per-tenant billing and authz stay out of scope.nuthatch nest bundle packs
a nest's authored inputs into one portable, content-addressed .bundle; nest load <bundle-or-url>
verifies and installs it, regenerating the decode registry and asserting it matches, so anyone runs
your exact nest. A registry (RFC-0019) is a filesystem path or any S3-compatible bucket
(AWS_* env, AWS_ENDPOINT for non-AWS): nest publish <bundle> --registry … --as name@version,
then nest load name@version --registry …. The registry is never mandatory; a bundle and
load <file|dir> need none.nuthatch publish sync --target s3://bucket/prefix copies a nest's sealed Parquet segments, its catalogue and a
provenance envelope to any S3-compatible bucket or a directory, and dev --publish-target keeps
the mirror current as segments seal, uploading in streamed parts so ingestion does not wait on the
bucket. The mirror is keyed by the nest's data identity, not its NID: an edit that moves the NID but not
the data identity, which is the cosmetic case "Safe upgrades" below describes, keeps publishing to
the same dataset, and any edit that changes what is decoded forks a new one.
publish status says what is still to upload, publish verify checks every object against the
local segment (--deep re-downloads and re-hashes), and doctor --publish puts the mirror in a
health check. A table's last few hundred rows wait to fold into its next segment and are not
mirrored until they do; on a nest whose chain has gone quiet, publish finalise lets them go.
Reading it needs no nuthatch: DuckDB, Trino or anything that reads Parquet, as
Reading a published nest describes.nuthatch seed --from <mirror> --dir <nest> fills a nest
that has not indexed from a path, an s3:// prefix or a public bucket's https:// address,
checking every file against the mirror's catalogue, and the next dev follows the chain from the
block after the mirror ends. The hashes show each file is the one the catalogue names, not that
the catalogue is true to the chain: seed from an operator you would trust to run the nest. Four
Graph Protocol nests are published at nuthatch-indexer.com/mirror.POST /_admin/move/<name> swaps a name to the new NID once it has caught up, with no gap.
--allow-breaking belongs to nuthatch migrate, the one-time move of a pre-2.0 directory.
Segments are content-addressed and shared across the runtime, so two nests that decode the same
contract hold one copy, not two. What a subgraph pays a full resync for, a cosmetic edit here
answers with a hash comparison.eth_call you don't need (RFC-0023). The Graph Foundation's figure is that
more than 70% of subgraphs call eth_call, much of it for reads that are derivable from the
events they already index - they fetch only because they have no way to derive. Nuthatch does:
nuthatch recipe add total_supply drops in a SQL view
that computes an ERC-20's totalSupply() as Σ minted − Σ burned from Transfer events - deterministic,
free, no archive node. That view runs at query time; it is not a DBSP circuit. It derives what a
subgraph pays an archive node to fetch. For the handful of
reads that aren't derivable but never change - decimals/symbol/name - nuthatch metadata fetch
calls once and caches forever.eth_getLogs is split and
retried, taking the provider's own suggested range when it offers one; a failure we cannot classify
is split once anyway, so an endpoint whose phrasing we have never seen still works rather than
stalling. Rate limits, transport blips and credential rejections are told apart - a rejected API key
is cooled down loudly instead of retried forever. And sealed segments now flush on a boundary derived
from the data, not from wherever a fetch window happened to stop, so two operators indexing the
same range produce byte-identical segments regardless of their RPC tuning./metrics - tip lag, rows decoded/sealed, reorgs, query counts, RSS.nuthatch is built to be fronted, not exposed raw - gateways, auth, and metering are the operator's
layer; nuthatch ships the guards (query timeout, row cap, result-byte cap, concurrency limit, a
filesystem-access denylist on /sql) and signals (/metrics) that make fronting it safe. It binds 127.0.0.1 by
default; --listen elsewhere and put a gateway in front. See docs/operators.md.
NUTHATCH_MAX_RSS and refuses a configuration that does not fit, naming
the largest value that would; since 4.10.0 an operator can set the headroom and the reservation
from measurements (NUTHATCH_RUNTIME_HEADROOM, NUTHATCH_INGESTION_RESERVATION;
capacity and sizing).dev is the serve command - it backfills, follows the tip, and serves in one process.
Copy-paste systemd and Docker recipes are in docs/operators.md.docs/operators.md is the full operating guide, and worth reading before you
run this for real rather than after. docs/verification.md is its
counterpart: an acceptance runbook that proves a deployment works, step by falsifiable step, and says
plainly which levels we have verified ourselves and which we have not.
Still deciding whether to trust it at all? docs/kicking-the-tyres.md
is a guide to falsifying nuthatch rather than confirming it: the cold walk, correctness against a
public subgraph, what it costs to keep running, a red-team pass on /sql, and where we have already
been wrong. We would rather you found the next one than a user did.
The guide covers the questions people actually hit:
A major version is a promise about stability, not a claim of completeness.
nuthatch.toml, mounts.toml and entities.toml keep
working; a data directory upgrades drop-in, with no re-index; and the HTTP, SQL and MCP surfaces do
not break. Upgrade only: a downgrade is not promised. Off-by-default cargo features are
experimental and not covered. The full terms are the
stability contract.docs/releases/.tests/upgrade_golden.rs).rust-toolchain.toml and the release
build all use. A version nobody tests is not a promise.dev runs in production today, hosting one nest or many.
Scaled mode is built and verified across real machines, but younger: until 0.9.3 its writer pool
did not index at all. If one process per box is enough, that is still the shape to reach for.What is deliberately not here: a billed or metered hosted service, a token, telemetry on by default, or any deployment story beyond binary + compose. Those are not backlog items; they are out of scope.
nuthatch binds 127.0.0.1 by default and is built to be fronted. Before you expose /sql to
anyone you do not trust, read SECURITY.md - and be on a current release:
/sql. DuckDB accepts a quoted function name and
the guard only matched an unquoted one, so SELECT * FROM "read_csv"('/etc/passwd') executed. Every
earlier release is affected./sql via ;-stacked COPY … TO.Both have published advisories on the repo's Security tab. The full pre-1.0 adversary pass, including
the findings we closed as not ours to fix and why, is in
docs/security-audit-2026-07-31.md.
docs/backlog.md; what each release changed is in docs/releases/.GOVERNANCE.md and the standing design brief
CLAUDE.md.Licensed under either of MIT or Apache-2.0 at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this work by you shall be dual licensed as above, without any additional terms or conditions.
Query an EVM contract's indexed history with SQL, via a local nuthatch nest and nuthatch dev.
{ "mcpServers": { "io.github.nightswatchhq-nuthatch": { "command": "docker", "args": [ "run", "-i", "--rm", "ghcr.io/nightswatchhq/nuthatch:4.0.0" ] } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ระเบียนนี้ไม่ได้ระบุตัวแปรสภาพแวดล้อมที่จำเป็น
Nuthatch ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-10 Query an EVM contract's indexed history with SQL, via a local nuthatch nest and nuthatch dev.