# ⛓️ Block MCP Server
A Model Context Protocol (MCP) server for Blockchain interactions. This server enables AI agents to interact with multiple blockchain networks, check financial data, and send real-time notifications to Telegram.
## 🛠️ Tools Included
1. **💰 Wallet Balance Checker:** Retrieves native token balances for any wallet address across Ethereum, Polygon, Arbitrum, Optimism, and Base simultaneously using public RPC nodes.
2. **📜 Frax Transactions:** Fetches the 5 latest transactions on the FRAX network, including both native transfers and ERC-20 token events.
3. **⛽ Gas Price Estimator:** Provides real-time gas fee estimates (in Gwei) across multiple blockchain networks to help determine transaction costs.
4. **💱 Crypto Converter:** Converts cryptocurrency and fiat values using real-time market rates (e.g., BTC to ETH or USDC to USD).
5. **🤖 Telegram Bot:** Programmatically posts updates, messages, or automated notifications to a specific Telegram chat or channel.
---
## ⚙️ Setup Instructions
### Prerequisites
- **Python 3.11+**
- **uv**
### 1. Environment Variables
Create a `.env` file in the root directory and populate it with your credentials:
```bash
# Telegram Configuration
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_CHAT_ID=your_numeric_chat_id
# Blockchain API Keys
FRAXSCAN_API_KEY=your_fraxscan_api_key
# Optional: CoinGecko API Key
COINGECKO_API_KEY=your_api_key
```
### 2. Installation
1. **Clone the repository:**
```bash
git clone <YOUR_REPO_URL_HERE>
cd <YOUR_REPO_NAME>
```
2. **Install dependencies:**
This project uses `uv` for fast dependency management.
```bash
make install
```
---
### 🚀 How to Run
The easiest way to test the tools is using the built-in Makefile command, which launches the MCP Inspector.
```bash
make dev
```
_Alternatively:_ `uv run fastmcp dev main.py`
## 📖 Usage & Examples
Below are example inputs for testing the tools in the MCP Inspector.
### 1. Wallet Balance Checker Tool (`wallet_check`)
Queries multiple public RPC endpoints to retrieve native balances across various chains.
- **Input:**
```json
{ "address": "0x..." }
```
- **Response:**
```json
{
"Ethereum": "1.2450 ETH",
"Arbitrum": "0.0000 ETH",
"Polygon": "150.3200 MATIC",
"Optimism": "0.0500 ETH",
"Base": "0.1200 ETH"
}
```
### 2. Frax Transaction History (`get_frax_transactions`)
Merges native and token transfer history from the Fraxscan API, sorted by timestamp.
- **Input:**
```json
{ "address": "0x4200000000000000000000000000000000000015" }
```
- **Response:**
```json
[
{
"time": "2026-01-30 18:00:00",
"amount": "0.5000 frxETH",
"token": "frxETH",
"type": "Native",
"hash": "0x..."
}
]
```
### 3. Gas Price Estimator (`get_gas_prices`)
Monitors real-time gas prices (in Gwei) to estimate transaction costs.
- **Input:**
```json
{}
```
- **Response:**
```json
{
"Ethereum": "🔴 45.2 Gwei",
"Base": "🟢 0.01 Gwei"
}
```
### 4. Crypto Converter (`convert_crypto`)
Converts time between timezones.
- **Input:**
```json
{
"amount": 1,
"from_coin": "bitcoin",
"to_coin": "ripple"
}
```
- **Response:**
```json
{
"Response": "1 BITCOIN = 1235999999.0 XRP (Rate: 95000)"
}
```
### 5. Telegram Bot (`send_telegram_message`)
Sends messages to your configured Telegram chat through a bot.
- **Input (Example: Addition):**
```json
{
"message": "Message from telegram bot"
}
```
- **Response:**
```json
{
"Results": "Message sent succesfully"
}
```
---
