# ⛓️ 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`)

This tool allows the AI to **send** notifications to your phone via Telegram.

#### 🔄 How the Flow Works (Sending Messages)

1. **User Trigger:** You give Claude a condition or a direct command (e.g., _"If ETH is below $2000, alert me"_).
2. **Decision:** Claude evaluates the condition. If true, it decides to call `send_telegram_message`.
3. **Execution:** The MCP server receives the text payload and makes an HTTP POST request to the Telegram Bot API.
4. **Confirmation:** The Telegram API confirms the delivery, and the MCP server reports back to Claude that the task is done.

#### 📝 Implementation Details

- **Input:**

```json
{
  "message": "The deployment was successful"
}
```

- **Response:**

```json
"Message sent successfully!"
```

#### 🤖 Agent Mode (Auto-Pilot)

This mode enables the AI to automatically check for new messages and respond to them in a continuous loop, while also performing other operations in between.

**Prompt to Initiate:**

```json
"I want you to run in Auto-Pilot Mode. Here is your loop:
1. **Check:** Run `telegram_read_messages`.
2. **Act:** If there is a NEW message (one you haven't answered yet), interpret it and use `telegram_reply` to send the answer.
3. **Wait:** If there are no new messages, carry out any pending commands then run `wait_for_seconds(4)`.
4. **Repeat:** Go back to Step 1.
Do not ask me for permission between steps. Just keep running this loop indefinitely."
```

**How the Loop Works:**

1. **Check:** The AI polls the Telegram API for incoming messages.
2. **Process:** It reads the content of any new user messages (e.g., a user asking "What is the price of BTC?").
3. **Action:** It uses other available tools (like `convert_crypto`) to find the answer.
4. **Reply:** It sends the answer back to the user via Telegram and waits for the next cycle.