Bankless Onchain MCP Server
MCP (Model Context Protocol) server for blockchain data interaction through the Bankless API.
Overview
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.
https://github.com/user-attachments/assets/95732dff-ae5f-45a6-928a-1ae17c0ddf9d
Features
The server provides the following onchain data operations:
Contract 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
Event Operations
- 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
Transaction Operations
- 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 addressmethod (string, required): The contract method to callinputs (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 eventstopic (string, required): Primary topic to filter eventsoptionalTopics (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
Installation
npm install @bankless/onchain-mcp
Usage
Environment Setup
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
Running the Server
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:
read_contract
// 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"
}
]
get_proxy
// Example call
{
"name": "get_proxy",
"arguments": {
"network": "ethereum",
"contract": "0x1234..."
}
}
// Example response
{
"implementation": "0xefgh..."
}
get_events
// 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..."]
}
]
}
build_event_topic
// Example call
{
"name": "build_event_topic",
"arguments": {
"network": "ethereum",
"name": "Transfer(address,address,uint256)",
"arguments": [
{ "type": "address" },
{ "type": "address" },
{ "type": "uint256" }
]
}
}
// Example response
"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
Development
Building from Source
# 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
Debug Mode
Integration with AI Models
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"
}
}
}
}
Error Handling
The server provides specific error types for different scenarios:
BanklessValidationError: Invalid input parametersBanklessAuthenticationError: API token issuesBanklessResourceNotFoundError: Requested resource not foundBanklessRateLimitError: API rate limit exceeded
Prompting Tips
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.
License
MIT