onchain-mcp

MCP (Model Context Protocol) server for blockchain data interaction through the Bankless API.

The Bankless Onchain MCP Server provides a framework for interacting with on-chain data via the Bankless API. It implements the Model Context Protocol (MCP) to allow AI models to access blockchain state and event data in a structured way.

The server provides the following onchain data operations:

• Read Contract State (read_contract): Read state from smart contracts on various blockchain networks.

  • Parameters: network, contract address, method, inputs, outputs
  • Returns: Contract call results with typed values

• Get Proxy (get_proxy): Retrieve proxy implementation contract addresses.

  • Parameters: network, contract address
  • Returns: Implementation contract address

• Get ABI (get_abi): Fetch the ABI (Application Binary Interface) for a contract.

  • Parameters: network, contract address
  • Returns: Contract ABI in JSON format

• Get Source (get_source): Retrieve the source code for a verified contract.

  • Parameters: network, contract address
  • Returns: Source code, ABI, compiler version, and other contract metadata

• Get Events (get_events): Fetch event logs for a contract based on topics.

  • Parameters: network, addresses, topic, optional topics
  • Returns: Filtered event logs

• Build Event Topic (build_event_topic): Generate an event topic signature from event name and argument types.

  • Parameters: network, event name, argument types
  • Returns: Event topic hash

• Get Transaction History (get_transaction_history): Retrieve transaction history for a user address.

  • Parameters: network, user address, optional contract, optional method ID, optional start block, include data flag
  • Returns: List of transactions with hash, data, network, and timestamp

• Get Transaction Info (get_transaction_info): Get detailed information about a specific transaction.

  • Parameters: network, transaction hash
  • Returns: Transaction details including block number, timestamp, from/to addresses, value, gas info, status, and receipt data

• read_contract

  • Read contract state from a blockchain
  • Input:
    • network (string, required): The blockchain network (e.g., "ethereum", "polygon")
    • contract (string, required): The contract address
    • method (string, required): The contract method to call
    • inputs (array, required): Input parameters for the method call, each containing:
      • type (string): The type of the input parameter (e.g., "address", "uint256")
      • value (any): The value of the input parameter
    • outputs (array, required): Expected output types, each containing:
      • type (string): The expected output type
  • Returns an array of contract call results

• get_proxy

  • Gets the proxy address for a given network and contract
  • Input:
    • network (string, required): The blockchain network (e.g., "ethereum", "base")
    • contract (string, required): The contract address
  • Returns the implementation address for the proxy contract

• get_events

  • Fetches event logs for a given network and filter criteria
  • Input:
    • network (string, required): The blockchain network (e.g., "ethereum", "base")
    • addresses (array, required): List of contract addresses to filter events
    • topic (string, required): Primary topic to filter events
    • optionalTopics (array, optional): Optional additional topics (can include null values)
  • Returns an object containing event logs matching the filter criteria

• build_event_topic

  • Builds an event topic signature based on event name and arguments
  • Input:
    • network (string, required): The blockchain network (e.g., "ethereum", "base")
    • name (string, required): Event name (e.g., "Transfer(address,address,uint256)")
    • arguments (array, required): Event arguments types, each containing:
      • type (string): The argument type (e.g., "address", "uint256")
  • Returns a string containing the keccak256 hash of the event signature

npm install @bankless/onchain-mcp

Before using the server, set your Bankless API token. For details on how to obtain your Bankless API token, head to https://docs.bankless.com/bankless-api/other-services/onchain-mcp

export BANKLESS_API_TOKEN=your_api_token_here

The server can be run directly from the command line:

npx @bankless/onchain-mcp

This server implements the Model Context Protocol (MCP), which allows it to be used as a tool provider for compatible AI models. Here are some example calls for each tool:

// Example call
{
  "name": "read_contract",
  "arguments": {
    "network": "ethereum",
    "contract": "0x1234...",
    "method": "balanceOf",
    "inputs": [
      { "type": "address", "value": "0xabcd..." }
    ],
    "outputs": [
      { "type": "uint256" }
    ]
  }
}

// Example response
[
  {
    "value": "1000000000000000000",
    "type": "uint256"
  }
]

// Example call
{
  "name": "get_proxy",
  "arguments": {
    "network": "ethereum",
    "contract": "0x1234..."
  }
}

// Example response
{
  "implementation": "0xefgh..."
}

// Example call
{
  "name": "get_events",
  "arguments": {
    "network": "ethereum",
    "addresses": ["0x1234..."],
    "topic": "0xabcd...",
    "optionalTopics": ["0xef01...", null]
  }
}

// Example response
{
  "result": [
    {
      "removed": false,
      "logIndex": 5,
      "transactionIndex": 2,
      "transactionHash": "0x123...",
      "blockHash": "0xabc...",
      "blockNumber": 12345678,
      "address": "0x1234...",
      "data": "0x...",
      "topics": ["0xabcd...", "0xef01...", "0x..."]
    }
  ]
}

// Example call
{
  "name": "build_event_topic",
  "arguments": {
    "network": "ethereum",
    "name": "Transfer(address,address,uint256)",
    "arguments": [
      { "type": "address" },
      { "type": "address" },
      { "type": "uint256" }
    ]
  }
}

// Example response
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"

# Clone the repository
git clone https://github.com/Bankless/onchain-mcp.git
cd onchain-mcp

# Install dependencies
npm install

# Build the project
npm run build

npm run debug

To integrate this server with AI applications that support MCP, add the following to your app's server configuration:

{
  "mcpServers": {
    "bankless": {
      "command": "npx",
      "args": [
        "@bankless/onchain-mcp"
      ],
      "env": {
        "BANKLESS_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

The server provides specific error types for different scenarios:

• BanklessValidationError: Invalid input parameters
• BanklessAuthenticationError: API token issues
• BanklessResourceNotFoundError: Requested resource not found
• BanklessRateLimitError: API rate limit exceeded

In order to guide an LLM model to use the Bankless Onchain MCP Server, the following prompts can be used:

ROLE:
• You are Kompanion, a blockchain expert and EVM sleuth. 
• You specialize in navigating and analyzing smart contracts using your tools and resources.

HOW KOMPANION CAN HANDLE PROXY CONTRACTS:
• If a contract is a proxy, call your “get_proxy” tool to fetch the implementation contract.  
• If that fails, try calling the “implementation” method on the proxy contract.  
• If that also fails, try calling the “_implementation” function.  
• After obtaining the implementation address, call “get_contract_source” with that address to fetch its source code.  
• When reading or modifying the contract state, invoke implementation functions on the proxy contract address (not directly on the implementation).

HOW KOMPANION CAN HANDLE EVENTS:
• Get the ABI and Source of the relevant contracts
• From the event types in the ABI, construct the correct topics for the event relevant to the question
• use the "get_event_logs" tool to fetch logs for the contract

KOMPANION'S RULES:
• Do not begin any response with “Great,” “Certainly,” “Okay,” or “Sure.”  
• Maintain a direct, technical style. Do not add conversational flourishes.  
• If the user’s question is unrelated to smart contracts, do not fetch any contracts.  
• If you navigate contracts, explain each step in bullet points.  
• Solve tasks iteratively, breaking them into steps.  
• Use bullet points for lists of steps.  
• Never assume a contract’s functionality. Always verify with examples using your tools to read the contract state.  
• Before responding, consider which tools might help you gather better information.  
• Include as much relevant information as possible in your final answer, depending on your findings.

HOW KOMPANION CAN USE TOOLS:
• You can fetch contract source codes, ABIs, and read contract data by using your tools and functions.  
• Always verify the source or ABI to understand the contract rather than making assumptions.  
• If you need to read contract state, fetch its ABI (especially if the source is lengthy).  

FINAL INSTRUCTION:
• Provide the best possible, concise answer to the user’s request. If it's not an immediate question but an instruction, follow it directly.
• Use your tools to gather any necessary clarifications or data.  
• Offer a clear, direct response and add a summary of what you did (how you navigated the contracts) at the end.

MIT