Bankless Onchain MCP Server

1# Bankless Onchain MCP Server
2 
3[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
4![Version](https://img.shields.io/badge/version-0.6.2-blue)
5 
6MCP (Model Context Protocol) server for blockchain data interaction through the Bankless API.
7 
8## Overview
9 
10The 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.
11 
12 
13https://github.com/user-attachments/assets/95732dff-ae5f-45a6-928a-1ae17c0ddf9d
14 
15 
16## Features
17 
18The server provides the following onchain data operations:
19 
20### Contract Operations
21 
22- **Read Contract State** (`read_contract`): Read state from smart contracts on various blockchain networks.
23    - Parameters: network, contract address, method, inputs, outputs
24    - Returns: Contract call results with typed values
25 
26- **Get Proxy** (`get_proxy`): Retrieve proxy implementation contract addresses.
27    - Parameters: network, contract address
28    - Returns: Implementation contract address
29 
30- **Get ABI** (`get_abi`): Fetch the ABI (Application Binary Interface) for a contract.
31    - Parameters: network, contract address
32    - Returns: Contract ABI in JSON format
33 
34- **Get Source** (`get_source`): Retrieve the source code for a verified contract.
35    - Parameters: network, contract address
36    - Returns: Source code, ABI, compiler version, and other contract metadata
37 
38### Event Operations
39 
40- **Get Events** (`get_events`): Fetch event logs for a contract based on topics.
41    - Parameters: network, addresses, topic, optional topics
42    - Returns: Filtered event logs
43 
44- **Build Event Topic** (`build_event_topic`): Generate an event topic signature from event name and argument types.
45    - Parameters: network, event name, argument types
46    - Returns: Event topic hash
47 
48### Transaction Operations
49 
50- **Get Transaction History** (`get_transaction_history`): Retrieve transaction history for a user address.
51    - Parameters: network, user address, optional contract, optional method ID, optional start block, include data flag
52    - Returns: List of transactions with hash, data, network, and timestamp
53 
54- **Get Transaction Info** (`get_transaction_info`): Get detailed information about a specific transaction.
55    - Parameters: network, transaction hash
56    - Returns: Transaction details including block number, timestamp, from/to addresses, value, gas info, status, and receipt data
57 
58## Tools
59 
60- **read_contract**
61    - Read contract state from a blockchain
62    - Input:
63        - `network` (string, required): The blockchain network (e.g., "ethereum", "polygon")
64        - `contract` (string, required): The contract address
65        - `method` (string, required): The contract method to call
66        - `inputs` (array, required): Input parameters for the method call, each containing:
67            - `type` (string): The type of the input parameter (e.g., "address", "uint256")
68            - `value` (any): The value of the input parameter
69        - `outputs` (array, required): Expected output types, each containing:
70            - `type` (string): The expected output type
71    - Returns an array of contract call results
72 
73- **get_proxy**
74    - Gets the proxy address for a given network and contract
75    - Input:
76        - `network` (string, required): The blockchain network (e.g., "ethereum", "base")
77        - `contract` (string, required): The contract address
78    - Returns the implementation address for the proxy contract
79 
80- **get_events**
81    - Fetches event logs for a given network and filter criteria
82    - Input:
83        - `network` (string, required): The blockchain network (e.g., "ethereum", "base")
84        - `addresses` (array, required): List of contract addresses to filter events
85        - `topic` (string, required): Primary topic to filter events
86        - `optionalTopics` (array, optional): Optional additional topics (can include null values)
87    - Returns an object containing event logs matching the filter criteria
88 
89- **build_event_topic**
90    - Builds an event topic signature based on event name and arguments
91    - Input:
92        - `network` (string, required): The blockchain network (e.g., "ethereum", "base")
93        - `name` (string, required): Event name (e.g., "Transfer(address,address,uint256)")
94        - `arguments` (array, required): Event arguments types, each containing:
95            - `type` (string): The argument type (e.g., "address", "uint256")
96    - Returns a string containing the keccak256 hash of the event signature
97 
98## Installation
99 
100```bash
101npm install @bankless/onchain-mcp
102```
103 
104## Usage
105 
106### Environment Setup
107 
108Before 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
109 
110```bash
111export BANKLESS_API_TOKEN=your_api_token_here
112```
113 
114### Running the Server
115 
116The server can be run directly from the command line:
117 
118```bash
119npx @bankless/onchain-mcp
120```
121 
122### Usage with LLM Tools
123 
124This 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:
125 
126#### read_contract
127 
128```javascript
129// Example call
130{
131  "name": "read_contract",
132  "arguments": {
133    "network": "ethereum",
134    "contract": "0x1234...",
135    "method": "balanceOf",
136    "inputs": [
137      { "type": "address", "value": "0xabcd..." }
138    ],
139    "outputs": [
140      { "type": "uint256" }
141    ]
142  }
143}
144 
145// Example response
146[
147  {
148    "value": "1000000000000000000",
149    "type": "uint256"
150  }
151]
152```
153 
154#### get_proxy
155 
156```javascript
157// Example call
158{
159  "name": "get_proxy",
160  "arguments": {
161    "network": "ethereum",
162    "contract": "0x1234..."
163  }
164}
165 
166// Example response
167{
168  "implementation": "0xefgh..."
169}
170```
171 
172#### get_events
173 
174```javascript
175// Example call
176{
177  "name": "get_events",
178  "arguments": {
179    "network": "ethereum",
180    "addresses": ["0x1234..."],
181    "topic": "0xabcd...",
182    "optionalTopics": ["0xef01...", null]
183  }
184}
185 
186// Example response
187{
188  "result": [
189    {
190      "removed": false,
191      "logIndex": 5,
192      "transactionIndex": 2,
193      "transactionHash": "0x123...",
194      "blockHash": "0xabc...",
195      "blockNumber": 12345678,
196      "address": "0x1234...",
197      "data": "0x...",
198      "topics": ["0xabcd...", "0xef01...", "0x..."]
199    }
200  ]
201}
202```
203 
204#### build_event_topic
205 
206```javascript
207// Example call
208{
209  "name": "build_event_topic",
210  "arguments": {
211    "network": "ethereum",
212    "name": "Transfer(address,address,uint256)",
213    "arguments": [
214      { "type": "address" },
215      { "type": "address" },
216      { "type": "uint256" }
217    ]
218  }
219}
220 
221// Example response
222"0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
223```
224 
225## Development
226 
227### Building from Source
228 
229```bash
230# Clone the repository
231git clone https://github.com/Bankless/onchain-mcp.git
232cd onchain-mcp
233 
234# Install dependencies
235npm install
236 
237# Build the project
238npm run build
239```
240 
241### Debug Mode
242 
243```bash
244npm run debug
245```
246 
247### Integration with AI Models
248 
249To integrate this server with AI applications that support MCP, add the following to your app's server configuration:
250 
251```json
252{
253  "mcpServers": {
254    "bankless": {
255      "command": "npx",
256      "args": [
257        "@bankless/onchain-mcp"
258      ],
259      "env": {
260        "BANKLESS_API_TOKEN": "your_api_token_here"
261      }
262    }
263  }
264}
265```
266 
267## Error Handling
268 
269The server provides specific error types for different scenarios:
270 
271- `BanklessValidationError`: Invalid input parameters
272- `BanklessAuthenticationError`: API token issues
273- `BanklessResourceNotFoundError`: Requested resource not found
274- `BanklessRateLimitError`: API rate limit exceeded
275 
276## Prompting Tips
277 
278In order to guide an LLM model to use the Bankless Onchain MCP Server, the following prompts can be used:
279 
280```
281ROLE:
282• You are Kompanion, a blockchain expert and EVM sleuth. 
283• You specialize in navigating and analyzing smart contracts using your tools and resources.
284 
285HOW KOMPANION CAN HANDLE PROXY CONTRACTS:
286• If a contract is a proxy, call your “get_proxy” tool to fetch the implementation contract.  
287• If that fails, try calling the “implementation” method on the proxy contract.  
288• If that also fails, try calling the “_implementation” function.  
289• After obtaining the implementation address, call “get_contract_source” with that address to fetch its source code.  
290• When reading or modifying the contract state, invoke implementation functions on the proxy contract address (not directly on the implementation).
291 
292HOW KOMPANION CAN HANDLE EVENTS:
293• Get the ABI and Source of the relevant contracts
294• From the event types in the ABI, construct the correct topics for the event relevant to the question
295• use the "get_event_logs" tool to fetch logs for the contract
296 
297KOMPANION'S RULES:
298• Do not begin any response with “Great,” “Certainly,” “Okay,” or “Sure.”  
299• Maintain a direct, technical style. Do not add conversational flourishes.  
300• If the user’s question is unrelated to smart contracts, do not fetch any contracts.  
301• If you navigate contracts, explain each step in bullet points.  
302• Solve tasks iteratively, breaking them into steps.  
303• Use bullet points for lists of steps.  
304• Never assume a contract’s functionality. Always verify with examples using your tools to read the contract state.  
305• Before responding, consider which tools might help you gather better information.  
306• Include as much relevant information as possible in your final answer, depending on your findings.
307 
308HOW KOMPANION CAN USE TOOLS:
309• You can fetch contract source codes, ABIs, and read contract data by using your tools and functions.  
310• Always verify the source or ABI to understand the contract rather than making assumptions.  
311• If you need to read contract state, fetch its ABI (especially if the source is lengthy).  
312 
313FINAL INSTRUCTION:
314• Provide the best possible, concise answer to the user’s request. If it's not an immediate question but an instruction, follow it directly.
315• Use your tools to gather any necessary clarifications or data.  
316• Offer a clear, direct response and add a summary of what you did (how you navigated the contracts) at the end.
317```
318 
319## License
320 
321MIT
322