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= 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

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.