mirror of
https://github.com/alibaba/higress.git
synced 2026-06-06 19:27:33 +08:00
Add the Blockscout MCP server (#2585)
This commit is contained in:
Alexander Kolotov
committed by
GitHub
GitHub
parent
8346b4a4a2
commit
c0133378a7
88
plugins/wasm-go/mcp-servers/mcp-blockscout/README.md
Normal file
88
plugins/wasm-go/mcp-servers/mcp-blockscout/README.md
Normal file
@@ -0,0 +1,88 @@
|
||||
# Blockscout MCP Server
|
||||
|
||||
Blockscout is an open-source blockchain explorer for inspecting and analyzing EVM-compatible blockchains. This MCP server for Blockscout wraps the official Blockscout multi-chain API, exposing blockchain data - balances, tokens, NFTs, contract metadata - via MCP so that AI agents and tools can access and analyze it contextually.
|
||||
|
||||
- [Blockscout Website](https://blockscout.com/)
|
||||
- [MCP Server Plugin GitHub repo](https://github.com/blockscout/mcp-server-plugin)
|
||||
|
||||
## Features
|
||||
|
||||
Blockscout MCP Server provides the following features:
|
||||
|
||||
- **Chain Information**: Get a list of supported blockchains.
|
||||
- **Address and Contract Analysis**: Resolve ENS names, get address balances, contract details, and retrieve contract ABIs.
|
||||
- **Token and NFT Data**: Look up tokens by symbol, and get detailed information on token holdings and NFTs for a given address.
|
||||
- **Transaction and Block History**: Retrieve information on blocks, get transaction history for an address, and get detailed information about specific transactions, including human-readable summaries.
|
||||
- **Event Logs**: Get decoded event logs for transactions or addresses.
|
||||
|
||||
## Usage Guide
|
||||
|
||||
The Blockscout MCP Server is in Beta and currently does not require authentication. This is subject to change.
|
||||
|
||||
### Generate URL
|
||||
|
||||
Log in to the [Higress MCP Marketplace](https://mcp.higress.ai) and generate a URL for either Streamable HTTP or SSE.
|
||||
|
||||
### Configure MCP Client
|
||||
|
||||
In your MCP Client configuration, add the following to the MCP Server list:
|
||||
|
||||
```json
|
||||
"mcpServers": {
|
||||
"mcp-blockscout": {
|
||||
"url": "https://mcp.higress.ai/mcp-blockscout/{user-specific-id}/sse"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
or in case of Streamable HTTP:
|
||||
|
||||
```json
|
||||
"mcpServers": {
|
||||
"mcp-blockscout": {
|
||||
"url": "https://mcp.higress.ai/mcp-blockscout/{user-specific-id}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Supported Tools
|
||||
|
||||
The following tools are available in the multi-chain configuration.
|
||||
|
||||
1. `__get_instructions__()` - Must be called before any other tool. Initializes the MCP server session.
|
||||
2. `get_chains_list()` - Gets the list of supported blockchain chains and their IDs.
|
||||
3. `get_address_by_ens_name(name)` - Converts an ENS domain name to its corresponding Ethereum address.
|
||||
4. `lookup_token_by_symbol(chain_id, symbol)` - Searches for token addresses by symbol or name.
|
||||
5. `get_contract_abi(chain_id, address)` - Retrieves the ABI (Application Binary Interface) for a smart contract.
|
||||
6. `get_address_info(chain_id, address)` - Gets comprehensive information about an address (balance, contract status, etc.).
|
||||
7. `get_tokens_by_address(chain_id, address)` - Returns detailed ERC20 token holdings for an address.
|
||||
8. `get_latest_block(chain_id)` - Returns the latest indexed block number and timestamp.
|
||||
9. `get_transactions_by_address(chain_id, address, age_from, age_to, methods)` - Gets native currency transfers and smart contract interactions for an address.
|
||||
10. `get_token_transfers_by_address(chain_id, address, age_from, age_to, token)` - Returns ERC-20 token transfers for an address.
|
||||
11. `transaction_summary(chain_id, transaction_hash)` - Provides a human-readable summary of a transaction.
|
||||
12. `nft_tokens_by_address(chain_id, address)` - Retrieves NFT tokens owned by an address.
|
||||
13. `get_block_info(chain_id, number_or_hash)` - Returns block information (timestamp, gas used, etc.).
|
||||
14. `get_transaction_info(chain_id, transaction_hash)` - Gets comprehensive transaction information.
|
||||
15. `get_transaction_logs(chain_id, transaction_hash)` - Returns transaction logs with decoded event data.
|
||||
16. `get_address_logs(chain_id, address)` - Gets logs emitted by a specific address with decoded event data.
|
||||
|
||||
## Example Prompts
|
||||
|
||||
```plaintext
|
||||
On which popular networks is `ens.eth` deployed as a contract?
|
||||
```
|
||||
|
||||
```plaintext
|
||||
What are the usual activities performed by `ens.eth` on the Ethereum Mainnet?
|
||||
Since it is a contract, what is the most used functionality of this contract?
|
||||
Which address interacts with the contract the most?
|
||||
```
|
||||
|
||||
```plaintext
|
||||
Calculate the total gas fees paid on Ethereum by address `0xcafe...cafe` in May 2025.
|
||||
```
|
||||
|
||||
```plaintext
|
||||
Which 10 most recent logs were emitted by `0xFe89cc7aBB2C4183683ab71653C4cdc9B02D44b7`
|
||||
before `Nov 08 2024 04:21:35 AM (-06:00 UTC)`?
|
||||
```
|
||||
387
plugins/wasm-go/mcp-servers/mcp-blockscout/mcp-server.yaml
Normal file
387
plugins/wasm-go/mcp-servers/mcp-blockscout/mcp-server.yaml
Normal file
@@ -0,0 +1,387 @@
|
||||
server:
|
||||
name: blockscout-mcp-server
|
||||
config:
|
||||
baseUrl: "https://mcp.blockscout.com/v1"
|
||||
tools:
|
||||
- name: __get_instructions__
|
||||
description: |
|
||||
This tool MUST be called BEFORE any other tool.
|
||||
Without calling it, the MCP server will not work as expected.
|
||||
It MUST be called once in a session.
|
||||
args: []
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_instructions"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_block_info
|
||||
description: |
|
||||
Get block information like timestamp, gas used, burnt fees, transaction count etc.
|
||||
Can optionally include the list of transaction hashes contained in the block. Transaction hashes are omitted by default; request them only when you truly need them, because on high-traffic chains the list may exhaust the context.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: number_or_hash
|
||||
description: "Block number or hash"
|
||||
type: string
|
||||
required: true
|
||||
- name: include_transactions
|
||||
description: "If true, includes a list of transaction hashes from the block."
|
||||
type: boolean
|
||||
required: false
|
||||
default: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_block_info"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_latest_block
|
||||
description: |
|
||||
Get the latest indexed block number and timestamp, which represents the most recent state of the blockchain.
|
||||
No transactions or token transfers can exist beyond this point, making it useful as a reference timestamp for other API calls.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_latest_block"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_address_by_ens_name
|
||||
description: |
|
||||
Useful for when you need to convert an ENS domain name (e.g. "blockscout.eth")
|
||||
to its corresponding Ethereum address.
|
||||
args:
|
||||
- name: name
|
||||
description: "ENS domain name to resolve"
|
||||
type: string
|
||||
required: true
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_address_by_ens_name"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_transactions_by_address
|
||||
description: |
|
||||
Retrieves native currency transfers and smart contract interactions (calls, internal txs) for an address.
|
||||
**EXCLUDES TOKEN TRANSFERS**: Filters out direct token balance changes (ERC-20, etc.). You'll see calls *to* token contracts, but not the `Transfer` events. For token history, use `get_token_transfers_by_address`.
|
||||
A single tx can have multiple records from internal calls; use `internal_transaction_index` for execution order.
|
||||
Use cases:
|
||||
- `get_transactions_by_address(address, age_from)` - get all txs to/from the address since a given date.
|
||||
- `get_transactions_by_address(address, age_from, age_to)` - get all txs to/from the address between given dates.
|
||||
- `get_transactions_by_address(address, age_from, age_to, methods)` - get all txs to/from the address between given dates, filtered by method.
|
||||
**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "Address which either sender or receiver of the transaction"
|
||||
type: string
|
||||
required: true
|
||||
- name: age_from
|
||||
description: "Start date and time (e.g 2025-05-22T23:00:00.00Z)."
|
||||
type: string
|
||||
required: false
|
||||
- name: age_to
|
||||
description: "End date and time (e.g 2025-05-22T22:30:00.00Z)."
|
||||
type: string
|
||||
required: false
|
||||
- name: methods
|
||||
description: "A method signature to filter transactions by (e.g 0x304e6ade)"
|
||||
type: string
|
||||
required: false
|
||||
- name: cursor
|
||||
description: "The pagination cursor from a previous response to get the next page of results."
|
||||
type: string
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_transactions_by_address"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_token_transfers_by_address
|
||||
description: |
|
||||
Get ERC-20 token transfers for an address within a specific time range.
|
||||
Use cases:
|
||||
- `get_token_transfers_by_address(address, age_from)` - get all transfers of any ERC-20 token to/from the address since the given date up to the current time
|
||||
- `get_token_transfers_by_address(address, age_from, age_to)` - get all transfers of any ERC-20 token to/from the address between the given dates
|
||||
- `get_token_transfers_by_address(address, age_from, age_to, token)` - get all transfers of the given ERC-20 token to/from the address between the given dates
|
||||
**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "Address which either transfer initiator or transfer receiver"
|
||||
type: string
|
||||
required: true
|
||||
- name: age_from
|
||||
description: "Start date and time (e.g 2025-05-22T23:00:00.00Z). This parameter should be provided in most cases to limit transfers and avoid heavy database queries. Omit only if you absolutely need the full history."
|
||||
type: string
|
||||
required: false
|
||||
- name: age_to
|
||||
description: "End date and time (e.g 2025-05-22T22:30:00.00Z). Can be omitted to get all transfers up to the current time."
|
||||
type: string
|
||||
required: false
|
||||
- name: token
|
||||
description: "An ERC-20 token contract address to filter transfers by a specific token. If omitted, returns transfers of all tokens."
|
||||
type: string
|
||||
required: false
|
||||
- name: cursor
|
||||
description: "The pagination cursor from a previous response to get the next page of results."
|
||||
type: string
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_token_transfers_by_address"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: lookup_token_by_symbol
|
||||
description: |
|
||||
Search for token addresses by symbol or name. Returns multiple potential matches based on symbol or token name similarity. Only the first 7 matches from the Blockscout API are returned.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: symbol
|
||||
description: "Token symbol or name to search for"
|
||||
type: string
|
||||
required: true
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/lookup_token_by_symbol"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_contract_abi
|
||||
description: |
|
||||
Get smart contract ABI (Application Binary Interface).
|
||||
An ABI defines all functions, events, their parameters, and return types. The ABI is required to format function calls or interpret contract data.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "Smart contract address"
|
||||
type: string
|
||||
required: true
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_contract_abi"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_address_info
|
||||
description: |
|
||||
Get comprehensive information about an address, including:
|
||||
- Address existence check
|
||||
- Native token (ETH) balance (provided as is, without adjusting by decimals)
|
||||
- ENS name association (if any)
|
||||
- Contract status (whether the address is a contract, whether it is verified)
|
||||
- Proxy contract information (if applicable): determines if a smart contract is a proxy contract (which forwards calls to implementation contracts), including proxy type and implementation addresses
|
||||
- Token details (if the contract is a token): name, symbol, decimals, total supply, etc.
|
||||
Essential for address analysis, contract investigation, token research, and DeFi protocol analysis.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "Address to get information about"
|
||||
type: string
|
||||
required: true
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_address_info"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_tokens_by_address
|
||||
description: |
|
||||
Get comprehensive ERC20 token holdings for an address with enriched metadata and market data.
|
||||
Returns detailed token information including contract details (name, symbol, decimals), market metrics (exchange rate, market cap, volume), holders count, and actual balance (provided as is, without adjusting by decimals).
|
||||
Essential for portfolio analysis, wallet auditing, and DeFi position tracking.
|
||||
**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "Wallet address"
|
||||
type: string
|
||||
required: true
|
||||
- name: cursor
|
||||
description: "The pagination cursor from a previous response to get the next page of results."
|
||||
type: string
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_tokens_by_address"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: transaction_summary
|
||||
description: |
|
||||
Get human-readable transaction summaries from Blockscout Transaction Interpreter.
|
||||
Automatically classifies transactions into natural language descriptions (transfers, swaps, NFT sales, DeFi operations)
|
||||
Essential for rapid transaction comprehension, dashboard displays, and initial analysis.
|
||||
Note: Not all transactions can be summarized and accuracy is not guaranteed for complex patterns.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: transaction_hash
|
||||
description: "Transaction hash"
|
||||
type: string
|
||||
required: true
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/transaction_summary"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: nft_tokens_by_address
|
||||
description: |
|
||||
Retrieve NFT tokens (ERC-721, ERC-404, ERC-1155) owned by an address, grouped by collection.
|
||||
Provides collection details (type, address, name, symbol, total supply, holder count) and individual token instance data (ID, name, description, external URL, metadata attributes).
|
||||
Essential for a detailed overview of an address's digital collectibles and their associated collection data.
|
||||
**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "NFT owner address"
|
||||
type: string
|
||||
required: true
|
||||
- name: cursor
|
||||
description: "The pagination cursor from a previous response to get the next page of results."
|
||||
type: string
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/nft_tokens_by_address"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_transaction_info
|
||||
description: |
|
||||
Get comprehensive transaction information.
|
||||
Unlike standard eth_getTransactionByHash, this tool returns enriched data including decoded input parameters, detailed token transfers with token metadata, transaction fee breakdown (priority fees, burnt fees) and categorized transaction types.
|
||||
By default, the raw transaction input is omitted if a decoded version is available to save context; request it with `include_raw_input=True` only when you truly need the raw hex data.
|
||||
Essential for transaction analysis, debugging smart contract interactions, tracking DeFi operations.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: transaction_hash
|
||||
description: "Transaction hash"
|
||||
type: string
|
||||
required: true
|
||||
- name: include_raw_input
|
||||
description: "If true, includes the raw transaction input data."
|
||||
type: boolean
|
||||
required: false
|
||||
default: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_transaction_info"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_transaction_logs
|
||||
description: |
|
||||
Get comprehensive transaction logs.
|
||||
Unlike standard eth_getLogs, this tool returns enriched logs, primarily focusing on decoded event parameters with their types and values (if event decoding is applicable).
|
||||
Essential for analyzing smart contract events, tracking token transfers, monitoring DeFi protocol interactions, debugging event emissions, and understanding complex multi-contract transaction flows.
|
||||
**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: transaction_hash
|
||||
description: "Transaction hash"
|
||||
type: string
|
||||
required: true
|
||||
- name: cursor
|
||||
description: "The pagination cursor from a previous response to get the next page of results."
|
||||
type: string
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_transaction_logs"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_address_logs
|
||||
description: |
|
||||
Get comprehensive logs emitted by a specific address.
|
||||
Returns enriched logs, primarily focusing on decoded event parameters with their types and values (if event decoding is applicable).
|
||||
Essential for analyzing smart contract events emitted by specific addresses, monitoring token contract activities, tracking DeFi protocol state changes, debugging contract event emissions, and understanding address-specific event history flows.
|
||||
**SUPPORTS PAGINATION**: If response includes 'pagination' field, use the provided next_call to get additional pages.
|
||||
args:
|
||||
- name: chain_id
|
||||
description: "The ID of the blockchain"
|
||||
type: string
|
||||
required: true
|
||||
- name: address
|
||||
description: "Account address"
|
||||
type: string
|
||||
required: true
|
||||
- name: cursor
|
||||
description: "The pagination cursor from a previous response to get the next page of results."
|
||||
type: string
|
||||
required: false
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_address_logs"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
- name: get_chains_list
|
||||
description: |
|
||||
Get the list of known blockchain chains with their IDs.
|
||||
Useful for getting a chain ID when the chain name is known. This information can be used in other tools that require a chain ID to request information.
|
||||
args: []
|
||||
requestTemplate:
|
||||
url: "{{.config.baseUrl}}/get_chains_list"
|
||||
method: GET
|
||||
argsToUrlParam: true
|
||||
responseTemplate:
|
||||
body: |
|
||||
{{ . }}
|
||||
Reference in New Issue
Block a user