1scan

1scan provides an MCP server that lets AI assistants query blockchain data through a unified API gateway. The MCP component exposes a suite of tools for interacting with multiple blockchain explorers (e.g., getAccountBalance, getTransactionByHash, getBlockByNumber, getLogs, getTokenInfo, etc.). Deploying the MCP server enables AI models to request blockchain state and relations directly within conversations, using the same familiar tool calls you’d use in a traditional API client. After starting both the API gateway and the MCP server, you can configure Cursor IDE (or other MCP clients) to point at the MCP endpoint (for example, http://localhost:3000/mcp/sse) and start issuing commands such as balance lookups, transaction inquiries, and contract ABI retrieval in natural language prompts.

The MCP tools are designed to be composable and cover common needs: balance checks (getAccountBalance, getTokenBalance), transaction details (getTransactionByHash, getTransaction, getTransactionReceipt), block information (getBlockByNumber, getBlockByHash), token and contract information (getContractABI, getContractSourceCode, getTokenInfo, getERC20Transfers, getERC721Transfers), logs and events (getLogs), gas pricing (getGasPrice), and validator data (getValidators). This enables AI assistants to fetch precise blockchain data needed for compliance checks, auditing, or data enrichment within conversations.

Prerequisites:

• Go to the 1scan repository and build or install the MCP server component, or use the provided binary if available.
• Ensure you have Node.js installed if you plan to run the MCP server via a Node-based launcher (as noted in the MCP configuration example).
• A valid config.json with API keys for the desired explorers (as shown in the Quick Start sample).

Install steps:

1. Install the API gateway and MCP server binaries (choose your preferred route):

   • If using a prebuilt binary, download and place it in your PATH.
   • If building from source (Go-based project steps in README):
     • git clone https://github.com/huahuayu/1scan.git
     • cd 1scan
     • make build

2. Prepare configuration:

   • Create a config.json with explorer network entries and API keys, e.g.: { "1": {"endpoint": "api.etherscan.io", "keys": {"YOUR_ETHERSCAN_API_KEY_1": 5, "YOUR_ETHERSCAN_API_KEY_2": 10}}, "56": {"endpoint": "api.bscscan.com", "keys": {"YOUR_BSCSCAN_API_KEY": 5}} }
   • Place config.json in a known path (e.g., /path/to/config.json).

3. Run the MCP server (example using the Node-based launcher in this documentation):

   • Ensure the MCP launcher script path is correct in mcp_config (path/to/1scan-mcp-server.js).
   • Start the MCP server: node path/to/1scan-mcp-server.js -config /path/to/config.json

4. Run the API gateway (if not already running as part of the same setup):

   • Follow the installation steps for the API gateway as described in the repository README (go install or make run-1scan for the gateway and MCP gateway).

Tips and caveats:

• Ensure you replace placeholders in config.json with your actual API keys and rate limits.
• The MCP server supports transport options (sse or stdio); choose the one compatible with your client (Cursor IDE typically uses SSE).
• If you encounter CORS or network issues, verify that the MCP endpoint URL configured in your MCP client matches the running port and path (e.g., http://localhost:3000/mcp/sse).
• Rate limiting is enforced per API key; distribute requests across keys to avoid throttling.
• When upgrading 1scan or its MCP component, re-check the API endpoints for the supported networks, as explorer endpoints occasionally change or require new API keys.
• For debugging, start the MCP server with a verbose log level if available to track requests and responses from the underlying explorers.