1scan - Blockchain Explorer API Gateway & MCP Server

A unified API gateway for integrating multiple etherscan-like blockchain explorer APIs with Model Context Protocol (MCP) support for AI assistants.

Overview

1scan provides two main components:

1. API Gateway: A unified endpoint for accessing multiple blockchain explorer APIs
2. MCP Server: Allows AI models (like Claude in Cursor IDE) to directly query blockchain data

Supported Blockchain Networks

Apply for your own API key from the corresponding blockchain explorer

Features

• 🔄 Unified API endpoint for multiple blockchain explorers
• ⚖️ API load balancing
• 🔑 API rate limit management
• 🎯 Custom API key support via URL parameters
• 🤖 MCP server for AI assistants to query blockchain data

Installation

From Go

go install github.com/huahuayu/1scan@latest

From Source

# Clone the repository
git clone https://github.com/huahuayu/1scan.git
cd 1scan

# Build both 1scan API server and MCP server
make build

Quick Start

1. Create Configuration File

Create a config.json file with your API keys:

{
  "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
    }
  }
}

Each chain entry contains:

• chainID: The blockchain network ID
• endpoint: The API endpoint for the blockchain explorer
• keys: Map of API keys and their rate limits (requests per second)

2. Run the API Server

# Run with default settings
1scan -config /path/to/config.json

# Or using make
make run-1scan

3. Run the MCP Server

# Run with default settings
1scanmcp -config /path/to/config.json # default serve at port 3000

# Or using make
make run-1scanmcp

# With custom settings
1scanmcp -config /path/to/config.json -port 3000 -path /mcp

Integrating with Cursor IDE

To use 1scan MCP in Cursor IDE:

1. Start both the API server and MCP server

   # Terminal 1
   make run-1scan
   
   # Terminal 2
   make run-1scanmcp
   

2. In Cursor IDE, go to Settings → AI → MCP Servers

3. Add a new MCP server with the URL:

{
  "mcpServers": {
    "1scan": {
      "url": "http://localhost:3000/mcp/sse"
    }
  }
}

4. Restart Cursor IDE if necessary

5. Now you can use blockchain data in your AI conversations:

   Can you check the balance of address 0x742d35Cc6634C0532925a3b844Bc454e4438f44e on Ethereum?
   

MCP Server Configuration

When running the MCP server, you can customize it with these parameters:

• -port: Port to run the MCP server on (default: "3000")
• -path: Path for the MCP server endpoint (default: "/mcp")
• -config: Path to configuration file (default: "config.json")
• -transport: Transport type (sse or stdio) (default: "sse")

Example:

1scanmcp -port 3000 -config /path/to/config.json

Available MCP Tools

The MCP server exposes these tools to AI models:

• getAccountBalance - Get the balance of an account on a specific blockchain
• getTokenBalance - Get the token balance of an account on a specific blockchain
• getTransactionByHash - Get transaction details by hash
• getBlockByNumber - Get block information by block number
• getContractABI - Get the ABI for a verified contract
• getContractSourceCode - Get the source code of a verified contract
• getTokenInfo - Get information about an ERC20 token
• getGasPrice - Get current gas price on a specific blockchain
• getLogs - Get event logs matching specified parameters
• getTransaction - Get details of a transaction by its hash
• getTransactionCount - Get the number of transactions sent from an address
• getTransactionReceipt - Get transaction receipt by transaction hash
• getBlockTransactionCountByNumber - Get the number of transactions in a block
• getBlockTransactionCountByHash - Get the number of transactions in a block by block hash
• getBlockByHash - Get information about a block by its hash
• getNormalTransactions - Get normal transactions by address
• getInternalTransactions - Get internal transactions by address or transaction hash
• getERC20Transfers - Get ERC-20 token transfer events by address or contract
• getERC721Transfers - Get ERC-721 NFT transfer events by address or contract
• getValidators - Get validator information (for networks with validator sets)
• getContractCreation - Get contract creation information
• getContractVerificationStatus - Check contract verification status

Example MCP Interactions

Here are examples of how to interact with blockchain data through the MCP interface:

# Get account balance
What's the ETH balance of vitalik.eth (0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045) on Ethereum?

# Check a token balance
What's the USDC balance of address 0x28C6c06298d514Db089934071355E5743bf21d60 on Ethereum?

# Examine a transaction
Can you analyze transaction 0xdd6d7f687c9821404ae8c2ea7de5cfb5a23fc4c01ef1e7f535748cb147aa76dd on Ethereum?

# Look up block information
What transactions were in Ethereum block 18700000?

# Get contract ABI
Can you show me the ABI for the USDC contract (0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48) on Ethereum?

# Analyze contract source code
I need to understand how the Uniswap V3 router works. Can you show me the source code for 0xE592427A0AEce92De3Edee1F18E0157C05861564 on Ethereum?

# Check multiple chains
What's the difference in gas fees between Ethereum and Arbitrum right now?

# Examine token information
Tell me about the tokenomics of the APE token on Ethereum.

Complete List of MCP Tools

The MCP server exposes these tools to AI models:

• getAccountBalance - Get the balance of an account on a specific blockchain
• getTokenBalance - Get the token balance of an account on a specific blockchain
• getTransactionByHash - Get transaction details by hash
• getBlockByNumber - Get block information by block number
• getContractABI - Get the ABI for a verified contract
• getContractSourceCode - Get the source code of a verified contract
• getTokenInfo - Get information about an ERC20 token
• getGasPrice - Get current gas price on a specific blockchain
• getLogs - Get event logs matching specified parameters
• getTransaction - Get details of a transaction by its hash
• getTransactionCount - Get the number of transactions sent from an address
• getTransactionReceipt - Get transaction receipt by transaction hash
• getBlockTransactionCountByNumber - Get the number of transactions in a block
• getBlockTransactionCountByHash - Get the number of transactions in a block by block hash
• getBlockByHash - Get information about a block by its hash
• getNormalTransactions - Get normal transactions by address
• getInternalTransactions - Get internal transactions by address or transaction hash
• getERC20Transfers - Get ERC-20 token transfer events by address or contract
• getERC721Transfers - Get ERC-721 NFT transfer events by address or contract
• getValidators - Get validator information (for networks with validator sets)
• getContractCreation - Get contract creation information
• getContractVerificationStatus - Check contract verification status

Troubleshooting MCP Integration

If you encounter issues connecting to the MCP server from Cursor:

1. Verify both servers are running:

   # Check if servers are running
   ps aux | grep 1scanmcp
   

2. Ensure the correct URL is configured in Cursor

License

MIT License