chainlens

chainlens

chainlens looks into EVM blockchains through Blockscout: what an address holds and has done, what is in a block or a transaction, which tokens and NFTs sit in a wallet, and what a verified contract's ABI and source say. Six chains are built in — Ethereum, Optimism, Gnosis, Polygon, Base, and Arbitrum One — and every answer comes from that chain's public Blockscout API v2 instance.

This package is a clean-room rebuild of the 16 tools documented in the README of the original Blockscout MCP server. The full documented set is covered; the wire mapping is described below, including the parts that are reconstructions.

How it talks to the service

No API key is required — public Blockscout instances are keyless:

# Optional: send a key as an x-api-key header
export BLOCKSCOUT_API_KEY="your key"
# Optional: override the per-chain base URL for any chain
export BLOCKSCOUT_API_URL="https://eth.blockscout.com/api/v2"

The base URL is chosen per chain_id from a built-in map: 1 Ethereum, 10 Optimism, 100 Gnosis, 137 Polygon, 8453 Base, 42161 Arbitrum One. An unknown chain_id is an error naming the known chains (unless BLOCKSCOUT_API_URL is set, in which case the override wins for any chain).

Wire-format notes. The original server routes most data tools through its PRO gateway; this rebuild maps them onto the public Blockscout API v2 (/addresses/..., /blocks/..., /transactions/..., /smart-contracts/..., /search). A few shapings are documented reconstructions and first live-smoke checks:

• ENS resolution uses mainnet /search?q=<name> and picks the first result carrying an address.
• read_contract POSTs {function_name, args, abi} to /smart-contracts/{address}/methods/read — the least-proven mapping.
• cursor arguments are forwarded as a cursor query parameter; Blockscout v2 paging normally uses next_page_params, so cursor support is a drift risk.
• age_from / age_to (and methods / token) filters are applied client-side over the first fetched page, not forwarded upstream.

Two tools never touch the network: __unlock_blockchain_analysis__ returns local guidance plus the chain list, and get_chains_list filters that list locally by name, chain id, or currency substring.

Install

npx @reneturcios/chainlens get_block_number '{"chain_id":"1"}'

Or run the container image:

docker run -i ghcr.io/cloudcorprecords/chainlens

The container defaults to the MCP server. Pass CLI arguments to use it as a CLI instead.

CLI

The CLI mirrors the tools: one subcommand per tool, taking its arguments as a single JSON object.

chainlens get_chains_list '{"query":"base"}'
chainlens get_address_info '{"chain_id":"1","address":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"}'
chainlens get_transactions_by_address '{"chain_id":"1","address":"0x...","age_from":"2026-10-01T00:00:00Z","age_to":"2026-10-26T23:59:59Z"}'
chainlens get_block_info '{"chain_id":"8453","number_or_hash":"latest"}'
chainlens --version

Exit codes: 0 on success, 1 on an API or validation error (the error names the problem), 2 for usage errors.

MCP server

One bin serves both faces. The mcp subcommand starts a stdio MCP server:

npx -y @reneturcios/chainlens mcp

MCP client configuration:

{
  "mcpServers": {
    "chainlens": {
      "command": "npx",
      "args": ["-y", "@reneturcios/chainlens", "mcp"]
    }
  }
}

Tools

Tool	Input	What it does
__unlock_blockchain_analysis__	—	Local: returns status, guidance, and the supported chain list.
get_chains_list	query	Local: the 6-chain list filtered by a name/id/currency substring.
get_address_by_ens_name	name (required)	Resolve an ENS name via mainnet search; returns the first result with an address.
lookup_token_by_symbol	chain_id, symbol (required)	Search a chain; returns token-type items (fallback: all items).
get_contract_abi	chain_id, address (required)	The ABI of a verified contract.
inspect_contract_code	chain_id, address (required), file_name	Source code and creation status of a verified contract.
get_address_info	chain_id, address (required)	Address balance, type, and metadata.
get_tokens_by_address	chain_id, address (required), cursor	Token balances held by an address.
get_block_number	chain_id (required), datetime	Latest block number and timestamp; echoes the requested datetime.
get_transactions_by_address	chain_id, address, age_from, age_to (required), methods, cursor	Address transactions; age and method filters applied client-side over the first page.
get_token_transfers_by_address	chain_id, address, age_from, age_to (required), token, cursor	ERC-20 transfers; age and token filters applied client-side over the first page.
nft_tokens_by_address	chain_id, address (required), cursor	NFT tokens (ERC-721, ERC-1155) held by an address.
get_block_info	chain_id, number_or_hash (required), include_transactions	Block details by number or hash.
get_transaction_info	chain_id, hash (required), include_raw_input	Transaction details by hash.
read_contract	chain_id, address, abi, function_name (required), args (JSON string, default []), block	Read a contract function (reconstructed wire mapping, see notes).
direct_api_call	chain_id, endpoint_path (required), query_params, method, json_body, cursor	Call any Blockscout API v2 endpoint path directly.

Development

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, fake fetch only, no network
npm run dev     # run the CLI from source via tsx

License

MIT — see LICENSE.