io.github.CloudCorpRecords/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

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.