Content
# Bankless Onchain MCP Server
## This project is no longer receiving updates
[](https://opensource.org/licenses/MIT)
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
## Tools
- **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
## Installation
```bash
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
```bash
export BANKLESS_API_TOKEN=your_api_token_here
```
### Running the Server
The server can be run directly from the command line:
```bash
npx @bankless/onchain-mcp
```
### Usage with LLM Tools
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
```javascript
// 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
```javascript
// Example call
{
"name": "get_proxy",
"arguments": {
"network": "ethereum",
"contract": "0x1234..."
}
}
// Example response
{
"implementation": "0xefgh..."
}
```
#### get_events
```javascript
// 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
```javascript
// 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
```bash
# 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
```bash
npm run debug
```
### Integration with AI Models
To integrate this server with AI applications that support MCP, add the following to your app's server configuration:
```json
{
"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 parameters
- `BanklessAuthenticationError`: API token issues
- `BanklessResourceNotFoundError`: Requested resource not found
- `BanklessRateLimitError`: 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
