nft-farm-mcp

Find free-mint NFT collections that went up, and the wallets farming them, ranked by secondary-market PnL read directly from chain state.

Ships as an MCP server (stdio) and a CLI. Works on any EVM chain with a Seaport deployment; Robinhood Chain by default.

• Reads only eth_getLogs / eth_call / eth_getTransaction. No API key, no account, no wallet. Every tool is read-only and never sends a transaction.

• Data comes from Seaport OrderFulfilled events (sales) and Transfer from 0x0 (mints). No third-party indexer.

• Requires Node ≥ 20.

Tiếng Việt: README.vi.md

Install

claude mcp add nft-farm -- npx -y nft-farm-mcp@latest

{
  "mcpServers": {
    "nft-farm": {
      "command": "npx",
      "args": ["-y", "nft-farm-mcp@latest"],
      // optional — public RPCs are rate-limited; a private endpoint helps a lot
      // on busy chains like Ethereum and Base
      "env": {
        "NFT_FARM_CHAIN": "robinhood",
        "NFT_FARM_RPC_BASE": "https://your-base-endpoint"
      }
    }
  }
}

The package has no runtime dependencies — viem and the MCP SDK are bundled, so npx fetches one 305 kB tarball instead of installing a dependency tree.

Two binaries ship: nft-farm-mcp is the MCP server, nft-farm is the CLI.

Related MCP server: SOL Claimer MCP Server

Tools

Recommended call order

// 1. confirm the chain is supported and see what a scan will cost
list_chains { "chain": "base", "days": 1 }

// 2. rank collections — start narrow, async is the safe default
scan_collections { "chain": "base", "days": 1, "top": 10, "probe": 20, "async": true }

// 3. poll until status leaves "running"
job_status { "jobId": "<id from step 2>" }

// 4. take the interesting collections further: who minted them?
scan_wallets { "chain": "base", "days": 1, "topCollections": 10, "minOverlap": 2, "async": true }

Pass async: true unless the window is genuinely small. A scan that exceeds the inline budget is started as a background job automatically, but the estimate is approximate — an explicit async: true can never time out, and costs one extra job_status round-trip when the scan turns out to be fast.

Arguments

Shared by scan_collections and scan_wallets

Chain

Window — omit all four and you get the last 7 days.

Cost / tuning

scan_collections only

scan_wallets only

list_chains / job_status

list_chains takes chain, rpcUrls, days — all optional. With no chain it just lists the built-ins.

job_status takes jobId (omit to list recent jobs) and cancel (abort instead of read).

Ranges are rejected, not clamped: days: 120 is a validation error.

Reading the output

Every tool returns a markdown table in content and typed data in structuredContent. All *Eth fields are decimal strings, not numbers — parse before comparing, or "9" sorts above "10". Amounts are in the chain's native token (chain.nativeSymbol: POL on Polygon, APE on ApeChain, BNB, AVAX), despite the Eth suffix.

collections[]

topWallets[], overlapWallets[]

What "realized" counts. A sale is credited to a wallet only when all three hold: it is a listing-side fill (Seaport bid fills have no resolvable seller), the collection is one of the seeded ones, and that wallet appears in the sampled minter set for it. It is therefore a floor on actual proceeds, not a full P&L.

How freeMint is decided. At most 8 mint transactions are sampled; freeMint is true when ≥ 80 % of them carry value == 0. It reads native tx.value only, so mints priced in ERC-20, routed through an aggregator, or batched (one transaction minting many tokens) are mis-priced.

Sampling. maxMints bounds how many mint events are fetched per collection, so minter sets are a sample of the largest minters, not the full holder list.

None of this is financial advice — verify on-chain before acting on a wallet.

When something goes wrong

job_status.status is one of running, done, error, cancelled. Stop polling on any of the last three, and read error when it is non-null. Poll every 5–15 s. Jobs live in the server process only: the last 32 are retained and all are lost if the server restarts.

Chain support

Built-in keys: robinhood, ethereum, base, optimism, arbitrum, polygon, zora, blast, apechain, abstract, bnb, avalanche.

chain also accepts a numeric id or a bare RPC URL. For an unknown chain the server detects and caches what it needs: chain id from eth_chainId, block time measured from two block timestamps, and the marketplace by probing Seaport's deterministic address (1.6 → 1.5 → 1.4) with getCode.

maxLogSpan defaults differ per chain — Ethereum 2 000, Base/OP/Polygon/Zora/ Blast/BNB/Avalanche 10 000, ApeChain/Abstract 20 000, Arbitrum 50 000, Robinhood 100 000, auto-detected chains 10 000 — then auto-tune to what the endpoint actually accepts. list_chains reports the current value.

Environment variables

Performance and caching

Block history is immutable, so decoded Seaport sales are cached in aligned block buckets under ~/.nft-farm/cache and reused; only the tip is re-fetched. Collection names, token standards, mint-cost probes and minter sets are cached too. Buckets within ~10 minutes of head are never cached, so a reorg cannot poison the store. Delete the directory to reset; cache: false bypasses it.

Those numbers are at probe 3–10. The default is probe: 80 over 7 days, which is minutes of work — another reason to start narrow and use async.

Cache size scales with sales volume: one day of Robinhood Seaport (73 k sale legs) is ~2.3 MB gzipped.

CLI

Same engine, no MCP client needed:

npx -y -p nft-farm-mcp nft-farm scan --days 7 --top 20
npx -y -p nft-farm-mcp nft-farm chains

# or from source
npm install && npm run build
npm run scan -- --chain base --days 1 --top 10
npm run wallets -- --days 1 --top 20 --min-overlap 2

nft-farm --help lists every flag. Flags mirror the MCP arguments (--chain, --rpc repeatable/comma-separated, --days, --top, --probe, --sort, --all for paid mints, --json, --concurrency, --max-span, --mint-probe-calls, --mint-lookback, --no-cache, --cache-dir).

Two CLI-only differences worth knowing: --min-sales defaults to 1 for both commands (the MCP scan_wallets uses 2), and --sort pnlFloor is an alias that sorts by floor price, not by floor PnL.

Development

npm run typecheck
npm test          # typecheck + bundle + MCP stdio smoke test

MCP_PLAN.md records the RPC measurements behind the design and the places the first design was wrong — useful if you port this to another chain or RPC provider.

MIT.