README.md•6.31 kB
# ChainFETCH MCP Server
A Model Context Protocol (MCP) server that provides access to [ChainFETCH](https://www.chainfetch.app) API - an AI-powered Ethereum blockchain intelligence platform with advanced semantic search capabilities.
## Features
ChainFETCH combines real-time blockchain streaming with AI-powered analysis to provide:
- **🔥 Live Block Streaming**: Real-time Ethereum block processing every ~12 seconds
- **🧠 AI-Powered Semantic Search**: Vector similarity search using Qwen3-Embedding-0.6B model
- **🤖 LLM-Enhanced Queries**: LLaMA 3.2 3B model for intelligent parameter selection
- **⚡ Multi-Modal Search**: Semantic, LLM, and JSON search options
- **🎯 Comprehensive Coverage**: Addresses, transactions, blocks, tokens, and smart contracts
## Available Tools
### Address Analysis
- `search_addresses_semantic` - AI-powered vector similarity search
- `search_addresses_json` - 150+ parameter filtering
- `search_addresses_llm` - Natural language to smart parameter selection
- `get_address_summary` - AI-generated address summaries
- `get_address_info` - Detailed address information
### Transaction Intelligence
- `search_transactions_semantic` - Semantic transaction search
- `search_transactions_json` - 254+ curated parameters
- `search_transactions_llm` - Natural language transaction queries
- `get_transaction_summary` - AI transaction summaries
- `get_transaction_info` - Detailed transaction data
### Block Analysis
- `search_blocks_semantic` - AI-powered block search
- `search_blocks_json` - 120+ block parameters
- `search_blocks_llm` - Natural language block queries
- `get_block_summary` - AI block summaries
- `get_block_info` - Detailed block information
### Token Intelligence
- `search_tokens_semantic` - Semantic token search
- `search_tokens_json` - Comprehensive token filtering
- `search_tokens_llm` - Natural language token queries
- `get_token_summary` - AI token summaries
- `get_token_info` - Detailed token information
- `get_nft_instance_info` - NFT instance details
### Smart Contract Analysis
- `search_smart_contracts_semantic` - AI contract search
- `search_smart_contracts_json` - 50+ contract parameters
- `search_smart_contracts_llm` - Natural language contract queries
- `get_smart_contract_summary` - AI contract summaries
- `get_smart_contract_info` - Detailed contract information
## Installation
### Prerequisites
- Node.js 18.0.0 or higher
- ChainFETCH API token from [chainfetch.app](https://www.chainfetch.app)
### Option 1: NPM Install (Recommended)
```bash
npm install -g chainfetch-mcp-server
```
### Option 2: From Source
```bash
git clone https://github.com/chainfetch/chainfetch-mcp-server.git
cd chainfetch-mcp-server
npm install
npm run build
npm link
```
## Configuration
### Environment Variables
Set your ChainFETCH API token:
```bash
export CHAINFETCH_API_TOKEN="your_api_token_here"
```
### For Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"chainfetch": {
"command": "npx",
"args": ["chainfetch-mcp-server"],
"env": {
"CHAINFETCH_API_TOKEN": "CHAINFETCH_API_TOKEN"
}
}
}
}
```
### For Claude via ngrok (HTTP Mode)
Start the server in HTTP mode:
```bash
MCP_HTTP_MODE=true chainfetch-mcp-server
```
In another terminal, start ngrok:
```bash
ngrok http 8000
```
Configure Claude MCP Connector with:
- **Server URL**: `https://your-ngrok-url.ngrok.app/streamable-http`
- **API Key**: Your ChainFETCH API token
## Usage Examples
### Semantic Search
```javascript
// Find whale addresses
search_addresses_semantic({
query: "whale addresses with high ETH balance and DeFi activity",
limit: 10
})
// Find suspicious transactions
search_transactions_semantic({
query: "high gas transactions with failed status",
limit: 5
})
```
### Natural Language Queries
```javascript
// LLM-powered address search
search_addresses_llm({
query: "Show me verified smart contracts deployed in the last month"
})
// LLM-powered transaction search
search_transactions_llm({
query: "Find large value transfers between exchanges"
})
```
### Structured Filtering
```javascript
// JSON search with specific parameters
search_addresses_json({
eth_balance_min: "10.0",
is_contract: true,
is_verified: true,
transactions_count_min: 1000,
limit: 20
})
```
### Detailed Analysis
```javascript
// Get comprehensive address information
get_address_info({
address: "0x742D35Cc6335C06576BE5A1D5E2A7df9e7B0E8df"
})
// Get AI-generated summary
get_address_summary({
address_hash: "0x742D35Cc6335C06576BE5A1D5E2A7df9e7B0E8df"
})
```
## API Coverage
This MCP server provides access to ChainFETCH's comprehensive API including:
- **150+ Address Parameters**: Balance, contract status, transaction counts, token holdings
- **254+ Transaction Parameters**: Value, gas, addresses, block info, token transfers
- **120+ Block Parameters**: Height, gas usage, transaction counts, miner info
- **Token Analysis**: ERC-20, ERC-721, ERC-1155 support with metadata
- **Smart Contract Intelligence**: Verification status, proxy patterns, ABI analysis
## Error Handling
The server provides detailed error messages for common issues:
- Missing API token
- Invalid addresses/hashes
- Rate limiting
- Network connectivity issues
## Development
### Local Development
```bash
# Install dependencies
npm install
# Run in development mode
npm run dev
# Run in HTTP mode for testing
npm run dev:http
```
### Testing with Claude
1. Set up your API token
2. Configure Claude Desktop or use ngrok
3. Test with simple queries first
4. Use the semantic search for exploratory analysis
## Support
- **Documentation**: [ChainFETCH API Docs](https://www.chainfetch.app/docs)
- **API Access**: [Get API Token](https://www.chainfetch.app)
- **Issues**: [GitHub Issues](https://github.com/chainfetch/chainfetch-mcp-server/issues)
## License
MIT License - see LICENSE file for details.
## Changelog
### v1.0.0
- Initial release
- Full ChainFETCH API integration
- Semantic, LLM, and JSON search modes
- Address, transaction, block, token, and smart contract tools
- Claude Desktop and ngrok HTTP support