# Sepolia FastMCP Server

A Model Context Protocol (MCP) server for interacting with the Sepolia Ethereum testnet. This server provides debugging tools and blockchain interaction capabilities through the MCP protocol using the FastMCP framework.

## Features

The server provides the following MCP tools:

- **get_tx**: Fetch raw transaction by hash
- **get_receipt**: Fetch transaction receipt and status by hash
- **verify_tx**: Verify transaction inclusion and confirmations
- **get_logs**: Query logs by address/topics and block range
- **decode_logs**: Decode logs using a provided contract ABI
- **current_block**: Get current chain head block number
- **get_balance**: Get ETH balance for an address

## Installation

1. Clone or download this repository
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

## Configuration

1. Copy `.env.example` to `.env`:

   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and set your Sepolia RPC URL:

   ```
   SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
   ```

   You can get a free RPC endpoint from:

   - [Infura](https://infura.io/)
   - [Alchemy](https://www.alchemy.com/)
   - [QuickNode](https://www.quicknode.com/)

## Usage

### Running the Server

#### Option 1: Using the run script (recommended)

```bash
./run_server.sh
```

#### Option 2: Direct execution

```bash
python mcp_sepolia_server_fastmcp.py
```

#### Option 3: With environment variable

```bash
SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY python mcp_sepolia_server_fastmcp.py
```

### Using with MCP Clients

This server is designed to be used with MCP clients like Claude Desktop. Configure your MCP client to run this script as a server process.

Example configuration for Claude Desktop:

```json
{
  "mcpServers": {
    "sepolia": {
      "command": "python",
      "args": ["/path/to/mcp_sepolia_server_fastmcp.py"],
      "env": {
        "SEPOLIA_RPC_URL": "https://sepolia.infura.io/v3/YOUR_KEY"
      }
    }
  }
}
```

## Project Structure

```
Sepolia-MCP/
├── mcp_sepolia_server_fastmcp.py  # Main FastMCP server implementation
├── run_server.sh                  # Convenience script to run the server
├── requirements.txt               # Python dependencies
├── pyproject.toml                 # Project configuration
└── README.md                      # This file
```

## Development

### Running Tests

```bash
python -m pytest
```

### Building

```bash
pip install build
python -m build
```

## License

MIT License - see LICENSE file for details.