Blockchain Lab MCP server + SDK

Give AI agents (Cursor, Claude Desktop/Code, Grok, any MCP client) real blockchain knowledge and live on-chain tools. 43 read-only tools over the Blockchain Lab Open Data API and public RPCs. No API keys.

Built by Blockchain Lab — blockchainlab.com

Tools

Tool	What it answers	Source
search_whitepapers	"Find papers on proof of stake from 2017" (600+ papers)	Blockchain Lab corpus
get_chain	Chain ID → RPCs, explorers, currency	chainid.network
top_defi_protocols / chains_tvl	TVL rankings, filter by category/chain	DefiLlama (nightly)
list_hackathons / list_events	Open hackathons, upcoming events	blockchainlab-feeds
list_grants	Grant programmes by ecosystem	curated, link-checked nightly
glossary	Plain-language definitions	blockchainlab.com
lookup_standard	EIP / ERC / BIP by number or title	ethereum/EIPs, ethereum/ERCs, bitcoin/bips
gas_prices	Live fees + USD cost (7 EVM chains, Bitcoin, Solana)	public RPCs, mempool.space, DefiLlama
decode_transaction	Decode any tx (call, args, logs, fees)	public RPCs + openchain
inspect_address	ENS, checksum, balance, contract/proxy/7702, ERC-20	public RPCs
decode_calldata / abi_utils	Decode calldata, selectors, encode calls	openchain / 4byte
stablecoins · defi_yields · bridges_tvl · dex_volumes · protocol_fees	Stablecoin pegs & supply, top yields, bridges by TVL, DEX volume, protocol fees	DefiLlama (nightly)
l2_metrics	L2 stage, stack, risks, TVS breakdown	L2BEAT (nightly)
security_incidents	Hacks/exploits by protocol, technique, date, size	DefiLlama hacks DB
sanctions_check	Screen addresses against OFAC SDN list	OFAC via 0xB10C
get_dataset	Any of the 20 Open Data API datasets, raw	blockchainlab-api
safe_info · safe_tx_hash · decode_safe_calldata	Safe owners/threshold/nonce; safeTxHash computed locally and checked against the Safe on-chain; decode execTransaction / MultiSend	public RPC
eip712_hash · verify_message	EIP-712 digest/domain/struct hash, recover signer, ERC-1271 check; EIP-191 recover	local + RPC
calldata_diff	Field-by-field diff of two calldata blobs	openchain / 4byte
contract_verification	Verified on Sourcify / Blockscout? compiler, licence, proxy	Sourcify, Blockscout
gas_history	Base fee / tips over ≤1,024 blocks with stats	eth_feeHistory
bridge_quotes	Live USDC/ETH bridge quotes compared	Across, LI.FI, Relay
token_approvals	Risky ERC-20 approvals + revoke calldata/link	Multicall3 + Revoke.cash link
ens_bulk	Resolve/reverse up to 50 ENS names with records	ENS
decode_solana_tx	Solana tx: instructions, programs, balance/token changes	Solana RPC
decode_psbt	Bitcoin PSBT / raw tx: inputs, outputs, fee rate, BIP-32	local (@scure/btc-signer)
address_labels	Who is this address? tags, ENS, token, OFAC	Blockscout, ENS, token lists
vanity_estimate	Vanity prefix difficulty/time; CREATE2 address	local
uniswap_price_impact	On-chain Uniswap v3 quote + price impact	QuoterV2 + slot0
mev_sandwich_check	Was this swap sandwiched?	eth_getBlockReceipts
rpc_health	Free public RPC latency / lag now + nightly	live probe + API
convert_units / storage_slot	wei↔ether etc., mapping/array/ERC-7201 slots (+ live read)	local + RPC

One-click install

Docker (GHCR) — no Node needed:

{ "mcpServers": { "blockchainlab": { "command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/blockchains/blockchainlab-mcp:latest"] } } }

Install (manual)

Requires Node ≥ 18. Not yet on the npm registry — install straight from GitHub:

Cursor — ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "blockchainlab": { "command": "npx", "args": ["-y", "github:Blockchains/blockchainlab-mcp"] }
  }
}

Claude Desktop — claude_desktop_config.json: same mcpServers block as above.

Claude Code

claude mcp add blockchainlab -- npx -y github:Blockchains/blockchainlab-mcp

Grok / any MCP client (stdio) — command npx, args -y github:Blockchains/blockchainlab-mcp.

From source

git clone https://github.com/Blockchains/blockchainlab-mcp && cd blockchainlab-mcp && npm ci
node bin/blockchainlab-mcp.js     # speaks MCP over stdio

Optional env: BLOCKCHAINLAB_API to point at a self-hosted copy of the data API.

Try asking your agent: "What are the top 5 lending protocols on Arbitrum by TVL?", "Decode tx 0x… on Base", "Which grant programmes fund Bitcoin developers?", "Summarise ERC-4337 and list related whitepapers."

SDK

import { BlockchainLab, onchain } from "blockchainlab-mcp";   // or from a GitHub install

const bl = new BlockchainLab();
await bl.searchWhitepapers({ query: "rollup", limit: 5 });
await bl.topProtocols({ category: "Lending", chain: "Arbitrum", limit: 5 });
await bl.findChain("8453");
await bl.standard("ercs", "4337");

await onchain.evmFees("base");
await onchain.decodeTx("ethereum", "0x…");
await onchain.resolveEns("vitalik.eth");

TypeScript

Type declarations ship in types/ (since v0.3.0) for every entry point: blockchainlab-mcp, /onchain, /onchain2 and /server. No @types package or declare module shim is needed. Requires TypeScript ≥ 5.7 (the re-exported @scure/btc-signer types use generic Uint8Array); with older TypeScript set skipLibCheck: true. Checked with 5.7, 5.9 and 7.0. Chain parameters are checked: Chain (EVM chains of the live tools), UniV3Chain, BlockscoutChain.

import { BlockchainLab, type DatasetDoc } from "blockchainlab-mcp";
import { rpc, type Chain } from "blockchainlab-mcp/onchain";
import { createServer } from "blockchainlab-mcp/server";   // McpServer with all 43 tools, for your own transport

const bl = new BlockchainLab();
const top = await bl.topProtocols({ category: "Lending", limit: 3 });   // { generated_at, source, results: Row[] }
const chain: Chain = "base";
const head: string = await rpc(chain, "eth_blockNumber");

types/onchain*.d.ts are generated from the JS sources (npm run types). types/sdk.d.ts and types/server.d.ts are hand-written. test/types.test.mjs fails if any of them drift from the runtime exports.

Tests (live, no mocks)

npm test   # type declarations (offline) + SDK against the live API + spawns the real MCP server over stdio and calls all 43 tools (fails if any listed tool is untested)

CI runs on Node 18/20/22 on every push and daily.

Related

Tools site · Open Data API · Lens · Labs · Roadmap

MIT. Read-only: the server never signs or sends transactions. Not financial advice.

Use as a building block

For AI agents and builders: read AGENTS.md (setup, commands, structure, rules), llms.txt (doc map) and the machine-readable blocks.json (schema). How all Blockchains blocks fit together: Build with Blocks · org catalogue: https://blockchains.github.io/blocks.json.

What it exports

Export	Type	Install / access
blockchainlab	mcp-stdio	npx -y github:Blockchains/blockchainlab-mcp
ghcr.io/blockchains/blockchainlab-mcp	docker	docker run -i --rm ghcr.io/blockchains/blockchainlab-mcp:0.3.0
blockchainlab-mcp	npm	npm i github:Blockchains/blockchainlab-mcp#v0.3.0
blockchainlab-mcp/server	npm	npm i github:Blockchains/blockchainlab-mcp#v0.3.0

blockchainlab exports: search_whitepapers, get_chain, top_defi_protocols, chains_tvl, list_hackathons, list_events, list_grants, glossary, lookup_standard, gas_prices, decode_transaction, inspect_address, decode_calldata, abi_utils, convert_units, storage_slot, stablecoins, defi_yields, bridges_tvl, dex_volumes, protocol_fees, l2_metrics, security_incidents, sanctions_check, get_dataset, safe_info, safe_tx_hash, decode_safe_calldata, eip712_hash, verify_message, calldata_diff, contract_verification, gas_history, bridge_quotes, token_approvals, ens_bulk, decode_solana_tx, decode_psbt, address_labels, vanity_estimate, uniswap_price_impact, mev_sandwich_check, rpc_health

blockchainlab-mcp exports: BlockchainLab, onchain, onchain2, toolLinks, DEFAULT_API, TOOLS_SITE, SITE

blockchainlab-mcp/server exports: createServer, main, VERSION

Minimal example (Cursor ~/.cursor/mcp.json, Claude Desktop or any stdio MCP client; tools/list returned 43 tools on 2026-10-04)

{ "mcpServers": { "blockchainlab": { "command": "npx", "args": ["-y", "github:Blockchains/blockchainlab-mcp"] } } }

Inputs → outputs

• In: tool call (MCP tools/call) JSON arguments per tool (see tools/list input schemas); BLOCKCHAINLAB_API (env) optional self-hosted API base
• Out: tool result (MCP content (JSON text)) data with generated_at/source fields and deep links to blockchainlab-tools pages

Composes with

• Blockchains/blockchainlab-api: data source for the dataset tools
• Blockchains/blockchainlab-tools: shares the on-chain logic (src/onchain*.js mirror assets/core*.js); results link to tool pages
• Blockchains/grokhack-forge: give a composed Grok app's developer agent these tools, or call the SDK in app code
• Blockchains/blockchainlab-sdk: TS + Python client for the same datasets (this package also ships TypeScript types since v0.3.0)
• Blockchains/blockchainlab-lens: same explorer deep links

Versioning & stability: beta. 0.x: tool names are kept stable, but new tools are added and output fields may grow. Releases are git tags + GitHub releases (latest v0.3.0: TypeScript declarations); not on the npm registry yet, so install from GitHub pinned to a tag (#v0.3.0) or use the GHCR image (:0.3.0, :latest). server.json is prepared for the MCP Registry.

Contributing

Issues and pull requests are welcome. Please read the contributing guide, code of conduct and security policy first.

---

Built by Blockchain Lab — blockchainlab.com

Release & packaging

• npm pack --dry-run is run in CI; the package is ready but deliberately not published to npm. To publish: npm publish (name blockchainlab-mcp).
• server.json is prepared for the official MCP Registry (io.github.Blockchains/blockchainlab-mcp) — publish with mcp-publisher publish after the npm release.
• Docker image ghcr.io/blockchains/blockchainlab-mcp (linux/amd64 + arm64) is built, smoke-tested over stdio (initialize + tools/list ≥ 43) and pushed on every push to main and on v* tags (:latest, :<version>, :sha-…).
• Releases: git tags vX.Y.Z with GitHub releases (first: v0.3.0). Install a release from GitHub with npm i github:Blockchains/blockchainlab-mcp#v0.3.0, or pull ghcr.io/blockchains/blockchainlab-mcp:0.3.0.